pygame Core
Build and debug a pygame game. New code targets pygame-ce 2.5.8, the maintained
community fork; it installs as pygame-ce and imports as pygame. Legacy pygame 2.6
code mostly runs unchanged; pygame-ce-only APIs such as FRect and get_frect() need the
fork, which getattr(pygame, "IS_CE", False) detects.
When to use
- Starting a pygame game, or fixing its loop, speed, input, drawing, sprite groups, collision, audio or text.
- Any project with
import pygame, whichever package provides it.
When not to use: Python questions unrelated to pygame; 3D; portable design work owned by the related skills below.
Workflow
- Check the install.
python -c "import pygame; print(pygame.version.ver, getattr(pygame, 'IS_CE', False))". Keep the project's package; for a new project usepip install pygame-ce. - Keep logic testable. Put rules in classes or functions that take
dtand an input snapshot, so a test can drive them without a window. Only the loop touches the display. - One loop per frame: drain events, update with a clamped
dt, draw,flip(). Use pixels per second, and float positions (FRectorVector2). - Load assets after
set_mode, thenconvert()/convert_alpha()once each. - Verify headless. Run the tests and a short scripted run with the dummy drivers (see the check below), then open the saved PNG. Report what ran. Feel, audio and real input still need a person: ask the user to play for a minute and report speed, controls and sound.
Pattern: a loop that can run headless
import argparse
import pygame
def main(argv=None):
ap = argparse.ArgumentParser()
ap.add_argument("--frames", type=int, default=0, help="quit after N frames (0 = run)")
ap.add_argument("--shot", help="save the last frame to this PNG")
args = ap.parse_args(argv)
pygame.init()
screen = pygame.display.set_mode((320, 180), pygame.SCALED) # before any convert()
clock = pygame.time.Clock()
sprites = pygame.sprite.Group(Player((160, 90)))
frame, running = 0, True
while running:
dt = min(clock.tick(60) / 1000, 0.05) # clamp stalls (window drag, debugger)
for event in pygame.event.get():
if event.type == pygame.QUIT:
running = False
sprites.update(dt, pygame.key.get_pressed())
screen.fill((18, 18, 28))
sprites.draw(screen)
pygame.display.flip()
frame += 1
if args.frames and frame >= args.frames:
if args.shot:
pygame.image.save(screen, args.shot)
running = False
pygame.quit()class Player(pygame.sprite.Sprite):
def __init__(self, pos):
super().__init__()
self.image = pygame.image.load("player.png").convert_alpha()
self.rect = self.image.get_frect(center=pos) # FRect keeps sub-pixel positions
self.speed = 120 # pixels per second
def update(self, dt, keys):
move = pygame.Vector2(keys[pygame.K_RIGHT] - keys[pygame.K_LEFT],
keys[pygame.K_DOWN] - keys[pygame.K_UP])
if move.length_squared(): # zero vectors cannot be scaled
move.scale_to_length(self.speed * dt) # same speed on diagonals
self.rect.center += moveUse KEYDOWN / MOUSEBUTTONDOWN events for one-off actions (jump, pause, click) and
key.get_pressed() for held movement. pygame.SCALED draws a small logical screen into a
larger window (handy for pixel art) and scales mouse events back to logical coordinates;
the docs still call it experimental.
The check to run
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy python -m unittest -v
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy python main.py --frames 120 --shot frame.pngA unit test sets the same variables before import pygame, calls pygame.init() and
pygame.display.set_mode((1, 1)) in setUp (so convert_alpha() works), feeds a fake key
snapshot and asserts on positions after a fixed number of update(1 / 60, keys) calls. The
PNG has the logical size (320×180 here), not the scaled window size. The dummy run proves
that the loop, loading and drawing work; it cannot show frame pacing or how input feels.
Gotchas
- Window freezes or shows "not responding" → the event queue is not drained every frame.
Call
pygame.event.get()(orpygame.event.pump()) once per frame, including in menus and loading screens. - Game runs faster on a faster machine → movement per frame instead of per second. Scale
by
dtfromclock.tick(). - Objects jump or pass through walls after a window drag or a breakpoint → the next
clock.tick()returns the whole stall. Clamp it:min(clock.tick(60) / 1000, 0.05). - Slow movement gets stuck or jitters →
Rectstores integers and truncates each update (rect.x += 0.5never moves). Useget_frect()/FRect(pygame-ce; groups and collision accept it) or keep aVector2position and assignrect.centerfrom it. ValueError: Can't normalize Vector of length zero(orCannot scale a vector with zero length) →normalize()/scale_to_length()ran with no keys held. Checklength_squared()first.pygame.error: No convert format has been set→convert()/convert_alpha()ran beforedisplay.set_mode(). Load images after opening the window.- Blits are slow → images were never converted. Convert each one once at load.
pygame.error: mixer not initializedon a server, in CI or on a machine without sound →pygame.init()does not raise when a module fails; it returns(passed, failed)and leaves the mixer off. SetSDL_AUDIODRIVER=dummyfor headless runs, or checkpygame.mixer.get_init()and skip audio.- Text rendering eats the frame budget →
font.renderevery frame. Cache the surface and re-render only when the string changes. import pygamegives the wrong version, ormodule 'pygame' has no attribute 'version'→pygameandpygame-cewere both installed into one environment: they share thepygamefolder, the last install wins, and removing either breaks the other. Runpip uninstall -y pygame pygame-ce, thenpip install pygame-ce.- Nothing appears → no
display.flip(), orscreen.fill()runs after the drawing. Draw back to front: background, world, sprites, HUD.
References
- Read
references/sprites-and-collision.mdwhen the game needs more than oneGroup:GroupSingleandLayeredUpdatesz-order, circle and mask (pixel-perfect) collision, spritesheet slicing, frame animation, sound effects and music, and cached text.
Related skills
input-systems,save-systems— engine-neutral rebinding and persistence.platformer,roguelike— genre rules that bind to this loop.love2d-core— the same loop in LÖVE;bevy-ecs— when a project outgrows pygame.
Version notes
Last verified: 2026-11-11.
- pygame-ce 2.5.8 (released 2026-08-09) is the latest release; it needs Python 3.10+ and ships wheels for CPython 3.10 to 3.15 and PyPy 3.11. It bundles SDL 2.32.10.
- Legacy pygame's latest release is 2.6.1 (2024-09-29).
- The loop, sprite, test and headless commands above, the error texts in Gotchas and the pygame/pygame-ce install clash were run with pygame-ce 2.5.8 on Python 3.12 and the SDL dummy drivers.
- Sources: pygame-ce on PyPI, pygame-ce releases, pygame-ce docs, pygame on PyPI.