Install & Compatibility
Where this runs
tested against v0.9.17 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.000s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sdl2
✓ import sdl2
Main module for core SDL2 functions (low-level ctypes bindings).
sdl2.ext
✓ import sdl2.ext
Higher-level wrappers for common SDL2 tasks (window, renderer, events).
sdl2.sdlimage
✓ import sdl2.sdlimage
Bindings for SDL_image (image loading).
sdl2.sdlmixer
✓ import sdl2.sdlmixer
Bindings for SDL_mixer (audio playback).
sdl2.sdlttf
✓ import sdl2.sdlttf
Bindings for SDL_ttf (TrueType font rendering).
This quickstart initializes SDL2 using `sdl2.ext`, creates a basic window, sets up a software renderer, and implements a simple event loop to handle closing the window. It demonstrates the high-level `sdl2.ext` API for common operations. Remember to install native SDL2 libraries on your system before running this code.
import sdl2
import sdl2.ext
RESOURCES = sdl2.ext.Resources(__file__, 'resources')
def run():
sdl2.ext.init()
window = sdl2.ext.Window("My PySDL2 Window", size=(800, 600))
window.show()
# Create a software renderer for the window
# Note: For hardware acceleration, you'd typically use sdl2.render.create_renderer
# and potentially integrate with OpenGL/Vulkan via PyOpenGL.
renderer = sdl2.ext.Renderer(window)
running = True
while running:
events = sdl2.ext.get_events()
for event in events:
if event.type == sdl2.SDL_QUIT:
running = False
break
# Clear the window to black
renderer.clear(sdl2.ext.Color(0, 0, 0))
# You can add drawing commands here
# renderer.draw_rect(..., sdl2.ext.Color(255, 0, 0))
renderer.present()
window.refresh()
sdl2.ext.quit()
return 0
if __name__ == '__main__':
import sys
sys.exit(run())
Debug
Known issues
gotchaPySDL2 requires the native SDL2 C libraries to be installed on your system. It does not bundle them. Without the native libraries, PySDL2 cannot function and will raise errors like 'sdl2.dll not found' or 'libSDL2-2.0.so.0: cannot open shared object file'.fixInstall SDL2 development libraries for your operating system (e.g., `libsdl2-dev` on Debian/Ubuntu, `sdl2` via Homebrew on macOS, download development libraries from libsdl.org for Windows).
affects: All versions
deprecatedThe PySDL2 project developers are actively working on PySDL3. While PySDL2 is still actively maintained for SDL2, new features and long-term development focus will eventually shift to SDL3, which introduces significant API changes. Consider the future implications for new projects.fixFor new projects, be aware of the upcoming SDL3 transition. For existing projects, continue with PySDL2, but plan for an eventual migration if long-term compatibility is needed. Monitor PySDL2/PySDL3 release announcements for migration guides.
affects: 0.9.17 and onward
gotchaPySDL2 exposes both low-level `ctypes`-based bindings (via `import sdl2`) and higher-level, more Pythonic wrappers (via `import sdl2.ext`). Mixing these incorrectly or directly accessing `ctypes` internals without understanding can lead to unexpected behavior or breakage.fixFor most applications, prefer the `sdl2.ext` module for common tasks like window management, event handling, and drawing. Use the raw `sdl2` module only when `sdl2.ext` does not provide the necessary functionality, and consult the documentation carefully.
affects: All versions
breakingA bug introduced in PySDL2 0.9.8 caused `sdl2.ext.Window.show()` to force software rendering, breaking compatibility with `sdl2.ext.Renderer` and PyOpenGL integration. This was promptly fixed and reverted in version 0.9.9.fixUpgrade to PySDL2 0.9.9 or later. If stuck on 0.9.8, avoid relying on hardware acceleration with `sdl2.ext.Renderer` or PyOpenGL, or manually manage rendering contexts.
affects: 0.9.8
Errors
Common errors & fixes
FileNotFoundError: Could not find dll 'sdl2.dll'
The native SDL2 C library (dll on Windows) is not found in the system PATH or the Python environment's search paths.
fixInstall the SDL2 development libraries for your operating system. For Windows, download from libsdl.org and ensure the DLLs are in your system PATH or the executable directory. For Linux, `sudo apt-get install libsdl2-dev` or equivalent. For macOS, `brew install sdl2`.
AttributeError: module 'sdl2' has no attribute 'init'
Attempting to call `sdl2.init()` directly. The top-level `sdl2` module provides low-level C bindings, not direct Python functions for initialization.
fixUse `sdl2.ext.init()` for convenient high-level initialization of SDL subsystems, or `sdl2.SDL_Init()` (followed by `sdl2.SDL_InitSubSystem()` for specific subsystems) for low-level control. Remember `sdl2.ext.quit()` or `sdl2.SDL_Quit()` to clean up.
sdl2.SDLError: Failed to create window: Could not initialize video driver
SDL's video subsystem could not be initialized. This can happen if SDL is not initialized at all, if there's no display server (e.g., SSH without X forwarding), or if graphics drivers are problematic.
fixEnsure `sdl2.ext.init()` or `sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)` is called before creating a window. If running remotely, ensure X forwarding is set up (`ssh -X`) or use a virtual display server like Xvfb. Check system graphics drivers.
Upgrade
Version history
0.9.17latest on PyPI · released Dec 30, 2024
Audit
Dependencies
No dependency data recorded yet.