PySDL2 DLL

2.32.0 verified Mon Apr 27 auth: no python

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.

pip install pysdl2-dll

Common errors

error ImportError: No module named sdl2.dll ↓

cause pysdl2-dll is not imported; PySDL2 expects the DLLs in its own package folder.

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))'.

error OSError: cannot load library 'SDL2': dlopen: library not found ↓

cause pysdl2-dll binaries not found by PySDL2, often due to missing environment variable or incorrect installation.

fix

Reinstall pysdl2-dll: 'pip uninstall pysdl2-dll; pip install pysdl2-dll'. Or set PYSDL2_DLL_PATH to the dll folder inside sdl2 package.

Warnings

gotcha Do NOT import from pysdl2_dll directly. This package only provides DLL files; use PySDL2's sdl2 module instead. ↓

fix Instead of 'from pysdl2_dll import *', use 'from sdl2 import *'.

breaking Version 2.30.0+ changed the DLL directory structure. Custom PYSDL2_DLL_PATH may need to point to the new location inside site-packages. ↓

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').

gotcha On macOS, the DLLs are universal binaries, but not signed/notarized. Gatekeeper may block execution. ↓

fix Use a terminal command: 'xattr -d com.apple.quarantine /path/to/libSDL2*.dylib' or add an exception in Security & Privacy.

Imports

DLLs
wrong
```
from pysdl2_dll import ...
```
correct
```
from sdl2 import dll
```
pysdl2-dll is not directly imported; its DLLs are loaded automatically by PySDL2 via sdl2.dll

Quickstart

Verify SDL2 binaries are loaded by initializing PySDL2.

import os
os.environ['PYSDL2_DLL_PATH'] = ''  # optional: clear custom path to use default
from sdl2 import *
import sdl2.ext
sdl2.ext.init()
# SDL2 is now ready to use