Installing Thonny + Pgzero

Quick setup

Download the script for your operating system. One double-click and it installs Python, uv, Thonny, pgzero, pygame-ce and all the starter code for you. Done in 5-10 minutes.

chmod +x install_linux_mac.sh && ./install_linux_mac.sh

Show all downloads

Manual setup

Thonny is a free Python editor made especially for beginners. It installs Python along with it. After installing, check which Python version you have: your game works with Python 3.13, 3.14 or 3.15.

Installing Thonny

Go to thonny.org and download the version for your operating system.

Windows

Download the .exe file and double-click it. Follow the installation steps (just click “Next”). Afterwards you’ll find Thonny in the Start menu.

macOS

Download the .pkg file and open it. Drag Thonny to your Applications folder. The first time you open it, you right-click and choose “Open” (so that macOS trusts it).

Linux

Open a terminal and type:

bash <(wget -qO - https://thonny.org/installer-for-linux)

Or use your package manager if Thonny is available (e.g. sudo apt install thonny on Ubuntu).

Checking the Python version

Pygame-ce and pgzero have ready-made versions for Python 3.13, 3.14 and 3.15. Newer versions (3.16 or higher) don’t work yet.

1. Open Thonny.
2. Look at the bottom right of the window. There you see the active Python version, e.g. Python 3.14.8.
3. Does it say 3.13, 3.14 or 3.15? Then everything is fine. Does it say something else? Then install Python 3.14 using the steps below.

Installing Python 3.14 and pointing Thonny at it

1. Go to python.org/downloads and click “All releases”. Find Python 3.14 in the list and download the installer for your operating system.
   • Windows: choose the Windows installer (64-bit) and leave the “Add Python to PATH” checkbox on.
   • macOS: choose the macOS 64-bit universal2 installer.
   • Linux: use your package manager, e.g. sudo apt install python3.14.
2. Run through the installation and finish it.
3. Open Thonny and click the Python version name at the bottom right (or go to Tools → Options → Interpreter).
4. Choose “Alternative Python 3 interpreter or virtual environment”.
5. Click the folder icon and browse to the Python 3.14 executable:
   • Windows: C:\Users\<jounaam>\AppData\Local\Programs\Python\Python314\python.exe
   • macOS: /Library/Frameworks/Python.framework/Versions/3.14/bin/python3
   • Linux: /usr/bin/python3.14
6. Click OK and restart Thonny.

The bottom right now says Python 3.14. Continue with installing Pygame-ce.

Installing Pygame-ce

Pgzero needs Pygame to work. We use pygame-ce, the maintained community version that also works on Python 3.14 and 3.15. In your code it stays just import pygame.

1. Open Thonny.
2. At the top, click Tools → Manage packages…
3. Type in the search box: pygame-ce
4. Click the search result and then Install.
5. Wait until the installation is done (you see “Done” at the bottom).

Installing Pgzero

Pgzero is the library you use to make games. This is how you install it:

1. Go back to Tools → Manage packages…
2. Type in the search box: pgzero
3. Click the search result and then Install.

Afterwards, check that the version is 1.2 or higher. You see the version on the right next to the name in the package list.

Testing whether everything works

Create a new file in Thonny and paste this code into it:

# test_setup.py
import pgzrun

WIDTH = 400
HEIGHT = 300

def draw():
    screen.fill((30, 30, 60))
    screen.draw.text("Pgzero works!", center=(200, 150), color="white")

pgzrun.go()

Save it as test_setup.py and click the green Run button in Thonny.

If everything is fine, a window opens with a dark blue background and the text “Pgzero works!”. Close the window by clicking the cross.

Not working?

Don’t panic! Have a look at the troubleshooting page for the most common errors and how to solve them.

VS Code (graduation track)

Have you already done a few Python sessions and do you want more control over your code? Then VS Code is a good next step. It is the editor real programmers use too.

When to switch?

Only when Thonny starts to feel too limited, for example when you want to manage several files at once, want to use Git, or are just curious how professional developers work.

Switching is not required. Thonny stays fine for beginners and short sessions.

Tip: give VS Code a try once you have done at least 3 sessions and you’re comfortable with the basics of Python.

Installing VS Code

Download VS Code via code.visualstudio.com. Choose the installer for your operating system (Windows, macOS or Linux) and follow the installation steps.

Installing the Python extension

VS Code works with extensions. For Python you need the official Microsoft extension:

1. Open VS Code.
2. Click the Extensions tab in the sidebar (or press Ctrl+Shift+X).
3. Search for ms-python.python.
4. Click Install.

After installing, VS Code automatically recognises Python files and you get autocomplete, error messages and more.

Installing uv

uv is a fast Python package manager that works much more easily than the standard pip. Install it via astral.sh/uv.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal after installing so that the uv command is available.

Setting up the project

Open a terminal in VS Code (`Ctrl+`` or via Terminal → New Terminal) and run these commands in your project folder:

# Use Python 3.13, 3.14 or 3.15
uv init --python 3.14
uv add pgzero pygame-ce pygbag

So put this line in your pyproject.toml, so that uv skips that old pygame:

[tool.uv]
exclude-dependencies = ["pygame"]

After that you have to tell VS Code which Python version the project uses:

1. Press Ctrl+Shift+P and type Python: Select Interpreter.
2. Choose the interpreter that is in your .venv folder (it looks like .venv/bin/python or .venv\Scripts\python.exe).

VS Code now uses the right environment with all the packages you just installed.

Running Pgzero

Open a terminal in VS Code and use:

uv run pgzrun main.py

Or create a launch.json in the .vscode/ folder so you can start with F5:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Pgzero: run current file",
      "type": "debugpy",
      "request": "launch",
      "module": "pgzero",
      "args": ["${file}"],
      "console": "integratedTerminal"
    },
    {
      "name": "Pygame: run current file",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

Create the .vscode/ folder in your project folder if it isn’t there yet, and save the file as launch.json. You then see the configurations back in the Run and Debug panel (Ctrl+Shift+D).

Running Pygame

For normal Pygame projects (without pgzrun) you use:

uv run python main.py

Or choose the “Pygame: run current file” configuration in the Run and Debug panel if you have created the launch.json.

PyCharm (graduation track)

PyCharm is a fully equipped IDE from JetBrains. You don’t need it to get going with Pgzero or Pygame, but if you want to grow further as a programmer it’s a handy step. Think of a built-in debugger, smart code completion and powerful refactoring tools.

When to switch?

Just keep working with Thonny as long as that feels fine. Only consider PyCharm once you:

• want to inspect variables while your code is paused (debugger),
• want to quickly rename functions or variables across your whole project (refactoring), or
• want autocomplete that also knows the types of your variables.

For beginners and most dojo sessions, Thonny is more than enough.

Installing PyCharm Community

Download the free Community edition at jetbrains.com/pycharm. Choose Community, not Professional. Professional is paid and you don’t need it.

1. Go to the download page and click Community-Free.
2. Run the installer and leave all the default settings as they are.
3. Start PyCharm. You don’t have to create a JetBrains account.

Creating a new project and setting up the interpreter

When you start PyCharm for the first time, you choose New Project.

PyCharm 2024.1 or newer with uv:

If you already have uv on your system (see the Thonny guide), PyCharm recognises it automatically. Under Python version, choose 3.13, 3.14 or 3.15 and let PyCharm create a uv environment.

Older version, or without uv using venv:

1. As Interpreter type, choose Virtualenv.
2. Under Base interpreter, select the Python installation on your system (usually python3 or python3.x).
3. Leave the Create a main.py welcome script checkbox on or turn it off. It doesn’t matter.

Then click Create. PyCharm creates the environment and opens the project.

Installing packages

You install pgzero, pygame-ce and pygbag through the settings:

1. Open File → Settings (on macOS: PyCharm → Preferences).
2. Navigate to Project: <naam> → Python Interpreter.
3. Click the + icon at the bottom right.
4. In the search box, search for pgzero and click Install Package. Do the same for pygame-ce and pygbag.
5. Close the window when all three are done.

Check that it all worked: on the right in the list you now see pgzero, pygame-ce and pygbag with their version numbers.

Run config for Pgzero

Pgzero works differently from a normal Python script: you start it as a module and pass your file name as an argument.

1. At the top, click Add Configuration… (or open Run → Edit Configurations…).
2. Click the + icon and choose Python.
3. Fill in:
   • Name: Pgzero
   • Run: set the choice to Module name (not Script path)
   • Module name: pgzero
   • Parameters: main.py
   • Working directory: the folder of your project (if it is still empty, click the folder icon and choose your project folder)
4. Click OK.

Then select the Pgzero configuration in the dropdown menu at the top and press the green play button to start your game.

Run config for Pygame

Pygame you do start as a normal script:

1. Open Run → Edit Configurations… again and click + → Python.
2. Fill in:
   • Name: Pygame
   • Run: leave the choice on Script path
   • Script path: browse to main.py in your project folder
   • Working directory: your project folder
3. Click OK.

Choose the Pygame configuration in the dropdown menu and press the play button.

That’s all. You now have two ready-made run configurations: one for Pgzero games and one for Pygame games. Just switch configuration in the dropdown menu at the top, depending on what you’re building.

Handy tips

• Using the debugger: Set a breakpoint by clicking to the left of a line number (red dot). Then start your run configuration with the bug button instead of the play button. PyCharm pauses on that line so you can look at your variables.
• Automatic imports: If PyCharm puts a red underline under a name you just wrote, press Alt+Enter to automatically add the right import statement at the top.
• Terminal: At the bottom you can open a built-in terminal (View → Tool Windows → Terminal). Handy for uv add or for running pygbag to publish.

Virtual environments (venv)

Imagine: you’re going on camp and you have to pack your backpack. For a sports camp you put different things in it than for a music camp. If you throw everything together, you never find anything back.

That’s how it works with Python projects too. Every project needs its own “backpack”: a virtual environment with exactly the right stuff in it.

What is a virtual environment?

A virtual environment (short: venv, pronounced “ven-vee”) is a separate folder on your computer that holds Python and all the extra packages for one project.

Say you have two projects:

• Project A uses Pygame version 2.5
• Project B uses Pygame version 2.6

Without virtual environments you could only install one version of Pygame on your computer. One of the projects would then stop working. With virtual environments every project has its own sealed box with the right version in it. They don’t get in each other’s way.

Metaphor: A virtual environment is like an own backpack per project. You put in exactly what that project needs, and the backpacks stand apart from each other in the cupboard.

Why do we use them?

1. No fighting between projects. Version 2.5 and 2.6 can both exist, each in its own environment.
2. Sharing is easy. If you share your project with a friend, you don’t have to send all the packages along. Your friend just creates their own virtual environment and installs the same packages.
3. Your computer stays tidy. You don’t install anything “just like that” on your whole computer. Everything stays neatly in the backpack of the right project.

How do you make a virtual environment with uv

uv is the Python package manager we use at CoderDojo. It can create and manage virtual environments.

Step 1: Open a terminal

• Windows: Press ⊞ Windows, type cmd and open “Command Prompt” (or use PowerShell).
• macOS / Linux: Open “Terminal”.

Step 2: Go to your project folder

cd pad/naar/jouw/projectmap

Step 3: Create the virtual environment

uv venv

uv now creates a .venv folder in your project folder. It holds a separate Python installation.

Want to use a specific Python version? That works too:

uv venv --python 3.14

Why would you do that? That way you’re sure you use a Python version that works with our game libraries. Choose 3.13, 3.14 or 3.15.

Step 4: Activate the virtual environment

The environment exists, but you still have to “switch it on”. We call that activating.

Windows (Command Prompt or PowerShell):

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

After activating you see (.venv) appear on the left in your terminal. That is the sign that you are now working inside your virtual environment.

(.venv) seppe@computer:~/project$

Step 5: Install packages

Now that your environment is active, you can install packages. They end up only in this one backpack:

uv add pgzero pygame-ce

So also put this line in your pyproject.toml:

[tool.uv]
exclude-dependencies = ["pygame"]

Step 6: Turning it off (deactivating)

Done programming? Just type:

deactivate

The (.venv) sign disappears and you work with the normal Python of your computer again.

What do you need to watch out for?

⚠️ Don’t forget to activate the environment

The most common mistake: you open a new terminal and forget to activate the virtual environment. Python then complains that it can’t find the packages, even though you did install them.

Solution: always activate first with .venv\Scripts\activate (Windows) or source .venv/bin/activate (macOS/Linux) before you start your program.

⚠️ Put .venv in .gitignore

The .venv folder is big (sometimes hundreds of MBs). You should not share it via Git or GitHub. Put .venv in your .gitignore file, so that Git skips it:

.venv/

Your friend just creates their own .venv with uv venv and installs the same packages via the pyproject.toml file that is in Git.

⚠️ Use uv run as a shortcut

No mood to activate and deactivate every time? uv has a handy shortcut:

uv run python main.py

This runs python main.py inside the virtual environment, even when it isn’t activated. uv figures out by itself which environment belongs to the project.

⚠️ Different terminals, different environments

If you activate the environment in one terminal, it is not automatically active in another terminal. You have to activate each terminal separately where you want to use the environment.

Summary

The golden rule: do you see (.venv) in your terminal? Then you’re good. Don’t see it? Activate first, program after.

What’s the difference with virtualenv and pip? Before uv there were already other tools, like virtualenv (for environments) and pip (for packages). With those you could do the same, but you had to use two separate commands and it worked a lot slower. uv does everything in one go, is much faster, and is a lot easier for beginners. That’s why at CoderDojo we prefer uv.

Having problems with your virtual environment? Have a look at Troubleshooting for common errors.

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.