{"id":21790,"library":"pysdl2-dll","title":"PySDL2 DLL","description":"Provides pre-built SDL2 binaries for PySDL2, ensuring cross-platform compatibility without requiring users to compile SDL2 themselves. Current version 2.32.0, released irregularly alongside SDL2 updates.","status":"active","version":"2.32.0","language":"python","source_language":"en","source_url":"https://github.com/a-hurst/pysdl2-dll","tags":["sdl2","gamedev","multimedia","binary distribution"],"install":[{"cmd":"pip install pysdl2-dll","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Python bindings for SDL2","package":"PySDL2","optional":false},{"reason":"Optional for pixel array operations","package":"numpy","optional":true}],"imports":[{"note":"pysdl2-dll is not directly imported; its DLLs are loaded automatically by PySDL2 via sdl2.dll","wrong":"from pysdl2_dll import ...","symbol":"DLLs","correct":"from sdl2 import dll"}],"quickstart":{"code":"import os\nos.environ['PYSDL2_DLL_PATH'] = ''  # optional: clear custom path to use default\nfrom sdl2 import *\nimport sdl2.ext\nsdl2.ext.init()\n# SDL2 is now ready to use","lang":"python","description":"Verify SDL2 binaries are loaded by initializing PySDL2."},"warnings":[{"fix":"Instead of 'from pysdl2_dll import *', use 'from sdl2 import *'.","message":"Do NOT import from pysdl2_dll directly. This package only provides DLL files; use PySDL2's sdl2 module instead.","severity":"gotcha","affected_versions":"all"},{"fix":"Set PYSDL2_DLL_PATH to the 'dll' subdirectory: e.g., os.environ['PYSDL2_DLL_PATH'] = os.path.join(sys.prefix, 'Lib', 'site-packages', 'sdl2', 'dll').","message":"Version 2.30.0+ changed the DLL directory structure. Custom PYSDL2_DLL_PATH may need to point to the new location inside site-packages.","severity":"breaking","affected_versions":">=2.30.0"},{"fix":"Use a terminal command: 'xattr -d com.apple.quarantine /path/to/libSDL2*.dylib' or add an exception in Security & Privacy.","message":"On macOS, the DLLs are universal binaries, but not signed/notarized. Gatekeeper may block execution.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure pysdl2-dll is installed (pip install pysdl2-dll) and do NOT import it; run a test script: 'from sdl2 import *; print(sdl2.SDL_Init(0))'.","cause":"pysdl2-dll is not imported; PySDL2 expects the DLLs in its own package folder.","error":"ImportError: No module named sdl2.dll"},{"fix":"Reinstall pysdl2-dll: 'pip uninstall pysdl2-dll; pip install pysdl2-dll'. Or set PYSDL2_DLL_PATH to the dll folder inside sdl2 package.","cause":"pysdl2-dll binaries not found by PySDL2, often due to missing environment variable or incorrect installation.","error":"OSError: cannot load library 'SDL2': dlopen: library not found"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}