PySDL2

0.9.17 · active · verified Fri Apr 17

PySDL2 provides comprehensive Python bindings for the SDL2 (Simple DirectMedia Layer) C library, along with its various extensions (SDL_image, SDL_mixer, SDL_ttf, SDL_gfx). It allows Python developers to create cross-platform multimedia applications, games, and graphical user interfaces. The current version is 0.9.17, with releases typically tied to updates in the underlying SDL2 library, though the pace has slowed as focus shifts towards SDL3 development.

Common errors

```
FileNotFoundError: Could not find dll 'sdl2.dll'
```
cause The native SDL2 C library (dll on Windows) is not found in the system PATH or the Python environment's search paths.

fix Install 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'
```
cause Attempting to call `sdl2.init()` directly. The top-level `sdl2` module provides low-level C bindings, not direct Python functions for initialization.

fix Use `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
```
cause 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.

fix Ensure `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.

Warnings

gotcha PySDL2 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'.
Fix: Install 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).
deprecated The 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.
Fix: For 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.
gotcha PySDL2 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.
Fix: For 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.
breaking A 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.
Fix: Upgrade 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.

Install

pip install pysdl2 Install PySDL2

Imports

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

Quickstart

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())

view raw JSON →