Pygame Community Edition

2.5.7 · active · verified Thu Apr 16

Pygame-ce (Pygame Community Edition) is an actively maintained, free and open-source Python library for multimedia applications and game development. It is a community-driven fork of the original Pygame, built on top of the Simple DirectMedia Layer (SDL) library. It offers frequent updates, bug fixes, performance enhancements, and improved compatibility with newer Python versions and operating systems. The current stable version is 2.5.7.

Common errors

```
ModuleNotFoundError: No module named 'pygame'
```
cause Pygame-ce is not installed, or the Python interpreter running the script does not have `pygame-ce` installed in its environment. This can happen with multiple Python installations or unactivated virtual environments.

fix Ensure `pygame-ce` is installed for the correct Python interpreter using `pip install pygame-ce`. If using a virtual environment, activate it first. Verify installation with `pip list`.
```
error: subprocess-exited-with-error × python setup.py egg_info did not run successfully.
```
cause This error during installation, especially on Linux or when building from source, often indicates missing system-level development dependencies for SDL or its components (e.g., `freetype2`).

fix Install required development packages for SDL and its dependencies. On Debian/Ubuntu: `sudo apt-get install build-essential libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libfreetype6-dev`. Refer to the `pygame-ce` compilation wiki for your specific OS.
```
pygame.error: No available video device
```
cause This error occurs when Pygame attempts to initialize a display but cannot find a suitable video backend. This is common on servers, CI/CD pipelines, or other headless environments without a graphical display server. (General Pygame knowledge)

fix For headless environments, consider using a virtual display server like Xvfb (e.g., `xvfb-run python your_game.py`) or setting the SDL video driver to 'dummy' if a visual output is not strictly required (`os.environ['SDL_VIDEODRIVER'] = 'dummy'` before `pygame.init()`).

Warnings

breaking Python 3.9 support was dropped in `pygame-ce 2.5.7`. PyPy 3.9 and 3.10 support was dropped in `pygame-ce 2.5.6`. Ensure your Python environment meets the `requires_python` specification (`>=3.10` for 2.5.7).
Fix: Upgrade Python to a supported version (e.g., Python 3.10-3.14).
breaking Pygame-ce is undergoing a significant migration to SDL3. While `2.5.x` versions aim for compatibility with SDL3 compilation, `pygame-ce 3.0` is planned to introduce breaking API changes related to this migration, including potential changes to mouse APIs and audio support.
Fix: Review `pygame-ce` 3.0 release notes and documentation carefully for migration guides when upgrading to `3.x` versions. Keep track of the SDL3 porting discussion on GitHub.
gotcha Installing `pygame-ce` while the original `pygame` package is already present can lead to conflicts, as both use the `pygame` import name. This often results in the original `pygame` being imported instead of `pygame-ce`.
Fix: Always run `pip uninstall pygame` before `pip install pygame-ce` to ensure only the Community Edition is active. Use a virtual environment to manage dependencies isolatedly.

Install

pip uninstall pygame # (if previously installed, to avoid package conflicts) Uninstall conflicting pygame (if present)
pip install pygame-ce --upgrade Install or upgrade pygame-ce

Imports

pygame
```
import pygame
```
Pygame-ce is designed to be a drop-in replacement for the original Pygame, using the same import name.

Quickstart

This basic example initializes Pygame-ce, creates a window, sets its title, and enters a game loop. Inside the loop, it handles the `QUIT` event to close the window, fills the screen with a blue color, draws a white circle, and updates the display. Finally, it properly shuts down Pygame.

import pygame
import sys

pygame.init()

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
SCREEN_TITLE = 'Pygame-CE Quickstart'

screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
pygame.display.set_caption(SCREEN_TITLE)

WHITE = (255, 255, 255)
BLUE = (0, 0, 255)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill(BLUE) # Fill the screen with blue

    # Example: Draw a white circle
    pygame.draw.circle(screen, WHITE, (SCREEN_WIDTH // 2, SCREEN_HEIGHT // 2), 50)

    pygame.display.flip() # Update the full display Surface to the screen

pygame.quit()
sys.exit()

view raw JSON →