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.

Your operating system is being detected...

Show all downloads

Tip

The script is safe: it only installs the same programs as the manual steps below. You can look at the source code by opening the file in Notepad or a text editor.

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).

Note

Use the version from thonny.org, not the version from the app store. That one is sometimes out of date.

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.
Tip

Does it say Python 3.13, 3.14 or 3.15? Skip the rest of this part and continue with Installing Pygame-ce.

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.

Note

Does installing pgzero get stuck on Python 3.14 or 3.15? That happens because pgzero automatically pulls in the classic pygame as well, and that one has no ready-made version for those versions. In that case use the one-click installation script at the top of this page, or choose Python 3.13 in Thonny.

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.