Common Pygame Errors and How to Fix Them

Most pygame errors come from a handful of mistakes. Here they are with the message you see, the cause and the fix. Many are not errors at all: the game runs but shows the wrong thing.

ModuleNotFoundError: No module named 'pygame'

ModuleNotFoundError: No module named 'pygame'

Pygame is not installed for the Python that ran your script. Install it with that same Python, python3 -m pip install pygame-ce (or py -m pip install pygame-ce on Windows), and select that interpreter in your editor. Installing pygame covers the other install errors.

A file named pygame.py in your folder causes a related error (module 'pygame' has no attribute 'init'): Python imports your file instead of the library. Rename it.

pygame.error: video system not initialized

pygame.error: video system not initialized

A display or event function ran while pygame was not running. The classic cause is pygame.quit() inside the loop:

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()          # the loop carries on and calls screen.fill()...
    screen.fill((0, 0, 0))

End the loop with a flag and quit after it:

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

If you want to stop the program at once, call pygame.quit() followed by sys.exit().

The window is "Not Responding"

The loop is not calling pygame.event.get(), or something blocks it: input(), time.sleep(), or a while loop inside the frame that waits for a key. The window must read its events every frame. Wait for things by checking state each frame instead (see the game loop).

Nothing shows, or the screen is black

Check, in order:

1. Is pygame.display.flip() called after drawing? Without it nothing reaches the window.
2. Is everything drawn after screen.fill()? A fill after drawing paints over it.
3. Are the coordinates inside the window? (0, 0) is the top-left corner and y grows downward.
4. Is the color the same as the background?

Everything leaves a trail

The screen is never cleared, so old frames stay. Start each frame with screen.fill(color) or by blitting a full background.

The game runs much too fast

There is no clock.tick(60) in the loop, so it runs as fast as the computer can. See Pygame Clock.

FileNotFoundError: No file found in working directory

FileNotFoundError: No file 'player.png' found in working directory '/Users/sam'.

Paths are relative to the folder Python was started from, not to your script. Build the path from the script's location, or run the game from its own folder. The full fix is on loading images; sounds and fonts give the same message.

pygame.error: No convert format has been set

pygame.error: No convert format has been set, try display.set_mode() or Window.get_surface().

convert() or convert_alpha() ran before the window existed. Call pygame.display.set_mode() first, then load and convert images.

ValueError: invalid color

ValueError: invalid color (color sequence must have size 3 or 4, and each element must be an integer in the range [0, 255])

A color has the wrong number of values or a value outside 0 to 255, often from a calculation. See pygame colors.

A Rect does not move

Adding a fraction to a pygame.Rect (rect.x += 0.5) adds nothing, because a Rect stores whole numbers. Keep the position in a float or a Vector2 and copy it into the Rect.

Holding a key moves only once

The movement is on the KEYDOWN event, which fires once per press. Use pygame.key.get_pressed() for held keys; see keyboard input.

TypeError: rect argument is invalid

pygame.draw.rect() wants a Rect or an (x, y, width, height) tuple. Passing only a position such as (x, y) gives this error. Pass the size too.

A working template

When a program misbehaves and you cannot see why, compare it with this minimal loop, which has every piece in the right order:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 320))
pygame.display.set_caption("Template")
clock = pygame.time.Clock()
player = pygame.Rect(220, 140, 40, 40)
running = True

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

    keys = pygame.key.get_pressed()
    player.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 4
    player.y += (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 4

    screen.fill((30, 30, 46))
    pygame.draw.rect(screen, (255, 196, 0), player)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Events, update, fill, draw, flip, tick, and pygame.quit() only after the loop.