Troubleshooting

Your code doesn’t work and you don’t know why? Don’t panic: almost every problem has a simple solution. Scroll through the list below and see if your error message is in it.

Pgzero or pygame won’t install

You see an error like No matching distribution found or Package not found when installing pgzero or pygame.

Cause: you’re using a Python version for which the library has no ready-made version yet. That happens with Python 3.16 or higher, and with the classic pygame on Python 3.14 and 3.15. Use Python 3.13, 3.14 or 3.15 and the community version pygame-ce instead of pygame.

Ubuntu 26.04 has Python 3.14 as default. The one-click installation script solves this automatically:

  • An existing Python 3.13, 3.14 or 3.15 is used; if there isn’t one, Python 3.14 is installed (via the deadsnakes PPA, ppa:deadsnakes/ppa, if apt doesn’t have that version)
  • Thonny is detected via PATH, snap, pip or flatpak
  • If Thonny is installed as a snap, the configuration is written to the right folder (~/snap/thonny/current/.config/Thonny/)
  • If apt install thonny doesn’t work, the script tries pip install --user thonny

Solution: use Python 3.13, 3.14 or 3.15 as active interpreter:

  • Thonny: see Installing Thonny + Pgzero → Checking the Python version.
  • VS Code: create your environment again with uv venv --python 3.14.
  • PyCharm: create a new interpreter and select Python 3.14 at Base interpreter.

pgzrun: command not found

This means Pgzero isn’t installed, or that you’re using the wrong Python version.

Solution: Open Thonny, go to Tools → Manage Packages, search for pgzero and click Install. Then restart Thonny and try again.

ModuleNotFoundError: No module named 'pygame'

Python can’t find the pygame library. This almost always happens because Thonny is using the wrong Python interpreter.

Solution: Look at the bottom right in the status bar of Thonny to see which interpreter is active. Choose the same interpreter you used during the installation. Then install pygame-ce again via Tools → Manage Packages.

Window opens and closes straight away

The program window flashes up briefly and then disappears again.

  • Pgzero: You need WIDTH and HEIGHT as separate variables at the top of your file, outside every function. Without those variables Pgzero doesn’t know how big the window should be and it stops straight away.
  • Pygame: You need an event loop that calls pygame.event.get() every frame. Without that call the window freezes and the operating system closes it.

Sounds do nothing

You call sounds.jump.play() but you hear nothing.

Check the following:

  1. Is there a sounds/ folder next to your main.py? The folder has to be in exactly the same place.
  2. Are the file names in lowercase and do you use underscores instead of spaces? For example jump.wav, not Jump.wav or jump sound.wav.
  3. Pgzero only accepts .wav files in the sounds/ folder. Pgzero loads them automatically, so you don’t have to import anything yourself.

Sound doesn’t work in pygame (session 5 and later)

You use pygame.mixer.Sound(...) but you hear nothing, no error message; the game just starts without sound.

Cause: Python looks for the sound file relative to the folder you start the script from, not the folder main.py is in. If you open VS Code from the project root and your script is in a subfolder, Python looks for sounds/hit.wav in the project root and doesn’t find it. The try/except in the starter silently catches that error.

Solution: Use __file__ to make the path absolute:

import os
_DIR = os.path.dirname(os.path.abspath(__file__))
snd_hit = pygame.mixer.Sound(os.path.join(_DIR, 'sounds/hit.wav'))

__file__ is always the path to main.py itself, no matter where you start the script from. The starter files from session 5 on already do this. Add the two lines just above loading the sounds if your own game doesn’t have this yet.

Images are not displayed

Your actor or background isn’t visible.

Check the following:

  1. Is there an images/ folder next to your main.py?
  2. Are all file names in lowercase? player.png works; Player.png doesn’t.
  3. Prefer .png files, because they work most reliably with Pgzero.

KeyError on an image

You get a KeyError when you create an Actor or load an image.

Cause: The name you pass has to match the file name exactly, without the extension. Actor('basket') looks for images/basket.png. One typo or one capital letter too many is enough to cause the error.

Solution: Check the file name in the images/ folder and make sure it matches exactly what you wrote in the code.

Chromebook or no installation rights

You can’t install Thonny or Pgzero because you don’t have administrator rights on the computer.

Solution: Work together with someone who does have Thonny, because pair programming is a good idea anyway! At home you can continue with the pygbag version: it runs your Pygame project straight in the browser, without installation.

Antivirus blocks the installation

Your installation attempt is interrupted or blocked by antivirus software.

Solution: Temporarily turn off the antivirus software during the installation, or ask a coach to put a portable version of Thonny on a USB stick. That version needs no installation and works straight from the stick.

Still stuck?

No problem. Just ask a coach during the session, or post your question in the CoderDojo chat. Include the exact error message (copy and paste the text from Thonny), then we can help you faster.