Thonny + Pgzero Installeren

Snel installeren

Download het script voor jouw besturingssysteem. Eén dubbelklik en het installeert Python, uv, Thonny, pgzero, pygame en alle startercode voor je. Klaar in 5-10 minuten.

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

Toon alle downloads

Handmatig installeren

Thonny is een gratis Python-editor die speciaal gemaakt is voor beginners. Het installeert Python automatisch mee. Controleer na de installatie wel welke Python-versie je hebt, want pygame en pgzero werken niet met Python 3.14 of hoger.

Thonny installeren

Ga naar thonny.org en download de versie voor jouw besturingssysteem.

Windows

Download het .exe-bestand en dubbelklik erop. Volg de installatiestappen (klik gewoon op “Next”). Daarna vind je Thonny terug in het Startmenu.

macOS

Download het .pkg-bestand en open het. Sleep Thonny naar je Programma’s-map. De eerste keer dat je het opent, klik je met de rechtermuisknop en kies je “Open” (zodat macOS het vertrouwt).

Linux

Open een terminal en typ:

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

Of gebruik je pakketbeheerder als Thonny beschikbaar is (bijv. sudo apt install thonny op Ubuntu).

Python-versie controleren

Pygame en pgzero hebben wheels nodig (voorgemaakte binaries) en die bestaan nog niet voor Python 3.14. Gebruik Python 3.13 (of 3.12).

1. Open Thonny.
2. Kijk rechtsonder in het venster. Daar staat de actieve Python-versie, bijv. Python 3.13.9.
3. Staat er 3.14 of hoger? Installeer dan Python 3.13 via de stappen hieronder.

Python 3.13 installeren en Thonny erop laten wijzen

1. Ga naar python.org/downloads en klik op “All releases”. Zoek Python 3.13 in de lijst en download de installer voor jouw besturingssysteem.
   • Windows: kies de Windows installer (64-bit) en laat het vinkje “Add Python to PATH” aanstaan.
   • macOS: kies de macOS 64-bit universal2 installer.
   • Linux: gebruik je pakketbeheerder, bijv. sudo apt install python3.13.
2. Doorloop de installatie en sluit hem af.
3. Open Thonny en klik rechtsonder op de Python-versienaam (of ga naar Tools → Options → Interpreter).
4. Kies “Alternatieve Python 3-interpreter of virtuele omgeving”.
5. Klik op het mapicoon en blader naar de Python 3.13-executable:
   • Windows: C:\Users\<jounaam>\AppData\Local\Programs\Python\Python313\python.exe
   • macOS: /Library/Frameworks/Python.framework/Versions/3.13/bin/python3
   • Linux: /usr/bin/python3.13
6. Klik op OK en herstart Thonny.

Rechtsonder staat nu Python 3.13. Ga door met het installeren van Pgzero.

Pgzero installeren

Pgzero is de bibliotheek waarmee je spelletjes maakt. Zo installeer je het:

1. Open Thonny.
2. Klik bovenaan op Tools → Manage packages…
3. Typ in het zoekvak: pgzero
4. Klik op het zoekresultaat en daarna op Install.
5. Wacht tot de installatie klaar is (je ziet “Done” onderaan).

Controleer daarna dat de versie 1.2 of hoger is. Je ziet de versie rechts naast de naam in de pakketlijst.

Pygame installeren

Pgzero heeft Pygame nodig om te werken. Installeer het op dezelfde manier:

1. Ga weer naar Tools → Manage packages…
2. Zoek op pygame
3. Klik op Install.

Pygame wordt automatisch gevonden door Pgzero, je hoeft er verder niets mee te doen.

Test of alles werkt

Maak een nieuw bestand aan in Thonny en plak deze code erin:

# test_setup.py
import pgzrun

WIDTH = 400
HEIGHT = 300

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

pgzrun.go()

Sla het op als test_setup.py en klik op de groene Run-knop in Thonny.

Als alles goed is, opent er een venster met een donkerblauwe achtergrond en de tekst “Pgzero werkt!”. Sluit het venster door het kruisje te klikken.

Werkt het niet?

Geen paniek! Kijk op de probleemoplossingspagina voor de meest voorkomende fouten en hoe je ze oplost.

VS Code (graduation track)

Heb je al een paar sessies Python gedaan en wil je meer controle over je code? Dan is VS Code een goede volgende stap. Het is de editor die echte programmeurs ook gebruiken.

Wanneer overstappen?

Pas wanneer Thonny te beperkt aanvoelt, bijvoorbeeld als je meerdere bestanden tegelijk wil beheren, Git wil gebruiken, of gewoon nieuwsgierig bent naar hoe professionele developers werken.

Overstappen is niet verplicht. Thonny blijft prima voor beginners en korte sessies.

Tip: probeer VS Code eens als je al minstens 3 sessies hebt meegedaan en je comfortabel bent met de basis van Python.

VS Code installeren

Download VS Code via code.visualstudio.com. Kies de installer voor jouw besturingssysteem (Windows, macOS of Linux) en volg de installatiestappen.

Python-extensie installeren

VS Code werkt met extensies. Voor Python heb je de officiële Microsoft-extensie nodig:

1. Open VS Code.
2. Klik op het Extensions-tabblad in de zijbalk (of druk op Ctrl+Shift+X).
3. Zoek naar ms-python.python.
4. Klik op Install.

Na de installatie herkent VS Code automatisch Python-bestanden en krijg je autocomplete, foutmeldingen en meer.

uv installeren

uv is een snelle Python-pakketbeheerder die veel makkelijker werkt dan de standaard pip. Installeer het 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

Herstart je terminal na de installatie zodat het uv-commando beschikbaar is.

Project Installeren

Open een terminal in VS Code (`Ctrl+`` of via Terminal → New Terminal) en voer deze commando’s uit in je projectmap:

# Installeer een python versie groter dan 3.13 en kleiner dan 3.14
uv init --python "python<3.14,>3.13"
uv add pgzero pygame pygbag

Daarna moet je VS Code vertellen welke Python-versie het project gebruikt:

1. Druk op Ctrl+Shift+P en typ Python: Select Interpreter.
2. Kies de interpreter die in je .venv-map staat (die ziet er uit als .venv/bin/python of .venv\Scripts\python.exe).

VS Code gebruikt nu de juiste omgeving met alle packages die je net hebt geïnstalleerd.

Pgzero runnen

Open een terminal in VS Code en gebruik:

uv run pgzrun main.py

Of maak een launch.json aan in de map .vscode/ zodat je met F5 kunt starten:

{
  "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"
    }
  ]
}

Maak de map .vscode/ aan in je projectmap als die er nog niet is, en sla het bestand op als launch.json. Daarna zie je de configuraties terug in het Run and Debug-paneel (Ctrl+Shift+D).

Pygame runnen

Voor gewone Pygame-projecten (zonder pgzrun) gebruik je:

uv run python main.py

Of kies in het Run and Debug-paneel de configuratie “Pygame: run current file” als je de launch.json hebt aangemaakt.

PyCharm (graduation track)

PyCharm is een volledig uitgeruste IDE van JetBrains. Je hebt het niet nodig om met Pgzero of Pygame aan de slag te gaan, maar als je verder wilt groeien als programmeur is het een handige stap. Denk aan een ingebouwde debugger, slimme code completion en krachtige refactoring-tools.

Wanneer overstappen?

Blijf gewoon met Thonny werken zolang dat prima voelt. Overweeg PyCharm pas als je:

• variabelen wilt inspecteren terwijl je code pauzeert (debugger),
• snel functies of variabelen wil hernoemen door heel je project heen (refactoring), of
• je autocomplete wilt die ook weet wat de types van je variabelen zijn.

Voor beginners en de meeste dojo-sessies is Thonny meer dan genoeg.

PyCharm Community installeren

Download de gratis Community-editie op jetbrains.com/pycharm. Kies Community, niet Professional. Professional is betaald en heb je niet nodig.

1. Ga naar de downloadpagina en klik op Community-Free.
2. Voer het installatieprogramma uit en laat alle standaardinstellingen staan.
3. Start PyCharm op. Je hoeft geen JetBrains-account aan te maken.

Nieuw project aanmaken en interpreter instellen

Wanneer je PyCharm voor het eerst opstart, kies je New Project.

PyCharm 2024.1 of nieuwer met uv:

Als je uv al op je systeem hebt staan (zie de Thonny-gids), herkent PyCharm dit automatisch. Kies bij Python version de optie 3.13 (of 3.12) en laat PyCharm een uv-omgeving aanmaken. Kies geen 3.14 of hoger, want pygame en pgzero hebben daarvoor nog geen wheels.

Oudere versie of zonder uv met venv:

1. Kies als Interpreter type de optie Virtualenv.
2. Selecteer bij Base interpreter de Python-installatie op je systeem (meestal python3 of python3.x).
3. Laat het vinkje Create a main.py welcome script staan of verwijder het. Het maakt niet uit.

Klik daarna op Create. PyCharm maakt de omgeving aan en opent het project.

Packages installeren

Je installeert pgzero, pygame en pygbag via de instellingen:

1. Open File → Settings (op macOS: PyCharm → Preferences).
2. Navigeer naar Project: <naam> → Python Interpreter.
3. Klik rechts onderaan op het +-icoon.
4. Zoek in het zoekvak naar pgzero en klik op Install Package. Doe hetzelfde voor pygame en pygbag.
5. Sluit het venster wanneer alle drie klaar zijn.

Controleer of alles gelukt is: rechts in de lijst zie je nu pgzero, pygame en pygbag met hun versienummers.

Run config voor Pgzero

Pgzero werkt anders dan een gewoon Python-script: je start het als een module en geeft je bestandsnaam mee als argument.

1. Klik bovenaan op Add Configuration… (of open Run → Edit Configurations…).
2. Klik op het +-icoon en kies Python.
3. Vul in:
   • Name: Pgzero
   • Run: zet de keuze op Module name (niet Script path)
   • Module name: pgzero
   • Parameters: main.py
   • Working directory: de map van je project (als die nog leeg is, klik op het mapicoon en kies je projectmap)
4. Klik op OK.

Selecteer daarna de Pgzero-configuratie in het dropdown-menu bovenaan en druk op de groene afspeelknop om je spel te starten.

Run config voor Pygame

Pygame start je wél als gewoon script:

1. Open opnieuw Run → Edit Configurations… en klik op + → Python.
2. Vul in:
   • Name: Pygame
   • Run: laat de keuze op Script path staan
   • Script path: blader naar main.py in je projectmap
   • Working directory: je projectmap
3. Klik op OK.

Kies de Pygame-configuratie in het dropdown-menu en druk op de afspeelknop.

Dat is alles. Je hebt nu twee kant-en-klare run-configuraties: één voor Pgzero-spellen en één voor Pygame-spellen. Wissel gewoon van configuratie in het dropdown-menu bovenaan naargelang wat je aan het bouwen bent.

Handige tips

• Debugger gebruiken: Zet een breekpunt door links van een regelnummer te klikken (rode stip). Start daarna je run-configuratie via de bug-knop in plaats van de afspeelknop. PyCharm pauzeert op die regel zodat je variabelen kunt bekijken.
• Automatisch importeren: Als PyCharm een rode onderstreping zet onder een naam die je net schreef, druk dan op Alt+Enter om automatisch het juiste import-statement bovenaan toe te voegen.
• Terminal: Onderin kun je een ingebouwde terminal openen (View → Tool Windows → Terminal). Handig voor uv add of het uitvoeren van pygbag voor publiceren.

Virtuele omgevingen (venv)

Stel je voor: je gaat op kamp en je moet je rugzak pakken. Voor een sportkamp stop je er andere dingen in dan voor een muziekkamp. Als je alles door elkaar gooit, vind je nooit iets terug.

Zo werkt het ook met Python-projecten. Elk project heeft zijn eigen “rugzak” nodig: een virtuele omgeving met precies de juiste spullen erin.

Wat is een virtuele omgeving?

Een virtuele omgeving (kortweg venv, spreek uit: “ven-vee”) is een aparte map op je computer waar Python én alle extra pakketten voor één project in zitten.

Stel dat je twee projecten hebt:

• Project A gebruikt Pygame versie 2.5
• Project B gebruikt Pygame versie 2.6

Zonder virtuele omgevingen zou je maar één versie van Pygame op je computer kunnen installeren. Het ene project zou dan niet meer werken. Met virtuele omgevingen heeft elk project zijn eigen afgesloten doos met de juiste versie erin. Ze staan elkaar niet in de weg.

Metafoor: Een virtuele omgeving is als een eigen rugzak per project. Je stopt er precies in wat dat project nodig heeft, en de rugzakken staan los van elkaar in de kast.

Waarom gebruiken we ze?

1. Geen ruzie tussen projecten. Versie 2.5 en 2.6 kunnen allebei bestaan, elk in hun eigen omgeving.
2. Delen is makkelijk. Als jij je project deelt met een vriend(in), hoef je niet alle pakketten mee te sturen. Je vriend(in) maakt gewoon een eigen virtuele omgeving en installeert dezelfde pakketten.
3. Je computer blijft opgeruimd. Je installeert niets “zomaar” op je hele computer. Alles blijft netjes in de rugzak van het juiste project.

Hoe maak je een virtuele omgeving met uv

uv is de Python-pakketbeheerder die we op CoderDojo gebruiken. Hij kan virtuele omgevingen maken én beheren.

Stap 1: Open een terminal

• Windows: Druk op ⊞ Windows, typ cmd en open “Command Prompt” (of gebruik PowerShell).
• macOS / Linux: Open “Terminal”.

Stap 2: Ga naar de map van je project

cd pad/naar/jouw/projectmap

Stap 3: Maak de virtuele omgeving aan

uv venv

uv maakt nu een mapje .venv aan in je projectmap. Daarin zit een aparte Python-installatie.

Wil je een specifieke Python-versie gebruiken? Dat kan ook:

uv venv --python 3.13

Waarom zou je dat doen? Omdat Pygame en Pgzero nog niet werken met Python 3.14 of hoger. Door --python 3.13 te gebruiken, ben je zeker dat alles werkt.

Stap 4: Activeer de virtuele omgeving

De omgeving bestaat, maar je moet hem nog “aanzetten”. Dat noemen we activeren.

Windows (Command Prompt of PowerShell):

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

Na activeren zie je links in je terminal (.venv) verschijnen. Dat is het teken dat je nú in je virtuele omgeving werkt.

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

Stap 5: Installeer pakketten

Nu je omgeving actief is, kun je pakketten installeren. Ze komen alleen in deze ene rugzak terecht:

uv add pgzero pygame

Stap 6: Uitschakelen (deactiveren)

Klaar met programmeren? Typ gewoon:

deactivate

Het (.venv)-teken verdwijnt en je werkt weer met de gewone Python van je computer.

Waar moet je op letten?

⚠️ Vergeet de omgeving niet te activeren

De meest gemaakte fout: je opent een nieuwe terminal en vergeet de virtuele omgeving te activeren. Python klaagt dan dat het pakketten niet vindt, ook al heb je ze wél geïnstalleerd.

Oplossing: activeer altijd eerst met .venv\Scripts\activate (Windows) of source .venv/bin/activate (macOS/Linux) voor je je programma start.

⚠️ Zet .venv in .gitignore

De map .venv is groot (soms honderden MB’s). Die moet je niet delen via Git of GitHub. Zet .venv in je .gitignore-bestand, zodat Git hem overslaat:

.venv/

Jouw vriend(in) maakt gewoon een eigen .venv aan met uv venv en installeert dezelfde pakketten via het pyproject.toml-bestand dat wél in Git zit.

⚠️ Gebruik uv run als shortcut

Geen zin om telkens te activeren en deactiveren? uv heeft een handige snelkoppeling:

uv run python main.py

Dit voert python main.py uit binnen de virtuele omgeving, ook al is die niet geactiveerd. uv snapt zelf welke omgeving bij het project hoort.

⚠️ Verschillende terminals, verschillende omgevingen

Activeer je de omgeving in de ene terminal, dan is hij niet automatisch actief in een andere terminal. Je moet elke terminal apart activeren waar je de omgeving wil gebruiken.

Samengevat

De gulden regel: zie je (.venv) in je terminal? Dan zit je goed. Zie je het niet? Activeer eerst, programmeer daarna.

Wat is het verschil met virtualenv en pip? Voor uv bestonden er al andere tools zoals virtualenv (voor omgevingen) en pip (voor pakketten). Daarmee kon je hetzelfde doen, maar je moest twee aparte commando’s gebruiken en het werkte een stuk trager. uv doet alles in één keer, is veel sneller, en is een stuk makkelijker voor beginners. Op CoderDojo gebruiken we daarom het liefst uv.

Heb je problemen met je virtuele omgeving? Kijk bij Problemen oplossen voor veelvoorkomende fouten.

Problemen oplossen

Je code werkt niet en je weet niet waarom? Geen paniek: bijna elk probleem heeft een eenvoudige oplossing. Blader door de lijst hieronder en kijk of jouw foutmelding ertussen staat.

Pgzero of pygame kan niet geïnstalleerd worden

Je ziet een fout als No matching distribution found of Package not found bij het installeren van pgzero of pygame.

Oorzaak: Python 3.14 of hoger heeft nog geen kant-en-klare binaries voor pygame of pgzero. Thonny of je IDE gebruikt een te nieuwe Python-versie.

Ubuntu 26.04 heeft Python 3.14 als standaard en biedt Python 3.13 niet via apt. Het één-klik installatiescript lost dit automatisch op:

• Python 3.13 wordt geïnstalleerd via de deadsnakes PPA (ppa:deadsnakes/ppa)
• Thonny wordt gedetecteerd via PATH, snap, pip of flatpak
• Als Thonny als snap geïnstalleerd is, wordt de configuratie naar de juiste map geschreven (~/snap/thonny/current/.config/Thonny/)
• Lukt apt install thonny niet, dan probeert het script pip install --user thonny

Oplossing: Installeer Python 3.13 (of 3.12) en stel die in als actieve interpreter:

• Thonny: zie Thonny + Pgzero Installeren → Python-versie controleren.
• VS Code: maak je omgeving opnieuw aan met uv venv --python 3.12.
• PyCharm: maak een nieuwe interpreter aan en selecteer Python 3.12 bij Base interpreter.

pgzrun: command not found

Dit betekent dat Pgzero niet geïnstalleerd is, of dat je een verkeerde Python-versie gebruikt.

Oplossing: Open Thonny, ga naar Tools → Manage Packages, zoek naar pgzero en klik op Install. Herstart Thonny daarna en probeer opnieuw.

ModuleNotFoundError: No module named 'pygame'

Python kan de pygame-bibliotheek niet vinden. Dit komt bijna altijd doordat Thonny de verkeerde Python-interpreter gebruikt.

Oplossing: Kijk rechtsonder in de statusbalk van Thonny welke interpreter actief is. Kies dezelfde interpreter die je bij de installatie hebt gebruikt. Installeer pygame dan opnieuw via Tools → Manage Packages.

Venster opent en sluit meteen

Het programmavenster flitst even op en verdwijnt dan weer.

• Pgzero: Je hebt WIDTH en HEIGHT nodig als losse variabelen bovenaan je bestand, buiten elke functie. Zonder die variabelen weet Pgzero niet hoe groot het venster moet zijn en stopt het direct.
• Pygame: Je hebt een event-loop nodig die elke frame pygame.event.get() aanroept. Zonder die aanroep bevriest het venster en sluit het besturingssysteem het.

Geluiden doen niets

Je roept sounds.jump.play() aan maar er is niets te horen.

Controleer het volgende:

1. Staat er een map sounds/ naast je main.py? De map moet op exact dezelfde plek staan.
2. Staan de bestandsnamen in kleine letters en gebruik je underscores in plaats van spaties? Bijvoorbeeld jump.wav, niet Jump.wav of jump sound.wav.
3. Pgzero accepteert alleen .wav-bestanden in de sounds/-map. Pgzero laadt ze automatisch, dus je hoeft zelf niets te importeren.

Geluid werkt niet in pygame (sessie 5 en later)

Je gebruikt pygame.mixer.Sound(...) maar er is niets te horen, geen foutmelding; het spel start gewoon zonder geluid.

Oorzaak: Python zoekt het geluidsbestand relatief aan de map waar je het script vanuit start, niet aan de map waar main.py staat. Open je VS Code vanuit de projectroot en staat je script in een submap, dan zoekt Python sounds/hit.wav in de projectroot en vindt het niet. De try/except in de starter vangt die fout stil op.

Oplossing: Gebruik __file__ om het pad absoluut te maken:

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

__file__ is altijd het pad naar main.py zelf, ongeacht vanwaar je het script start. De starter-bestanden vanaf sessie 5 doen dit al. Voeg de twee regels toe net boven het laden van geluiden als je eigen game dit nog niet heeft.

Afbeeldingen worden niet weergegeven

Je actor of achtergrond is niet zichtbaar.

Controleer het volgende:

1. Staat er een map images/ naast je main.py?
2. Zijn alle bestandsnamen in kleine letters? player.png werkt; Player.png niet.
3. Gebruik bij voorkeur .png-bestanden, want die werken het betrouwbaarst met Pgzero.

KeyError bij een afbeelding

Je krijgt een KeyError wanneer je een Actor aanmaakt of een afbeelding laadt.

Oorzaak: De naam die je meegeeft moet exact overeenkomen met de bestandsnaam, zonder extensie. Actor('basket') zoekt naar images/basket.png. Een typfout of een hoofdletter te veel is genoeg om de fout te veroorzaken.

Oplossing: Controleer de bestandsnaam in de images/-map en zorg dat die exact overeenkomt met wat je in de code hebt geschreven.

Chromebook of geen installatierechten

Je kunt Thonny of Pgzero niet installeren omdat je geen beheerdersrechten hebt op de computer.

Oplossing: Werk samen met iemand die Thonny wél heeft staan, want pair-programming is sowieso een goed idee! Thuis kun je verder via de pygbag-versie: die draait je Pygame-project rechtstreeks in de browser, zonder installatie.

Antivirus blokkeert de installatie

Je installatiepoging wordt onderbroken of geblokkeerd door antivirussoftware.

Oplossing: Schakel de antivirussoftware tijdelijk uit tijdens de installatie, of vraag een coach om een portable versie van Thonny op een USB-stick te zetten. Die versie heeft geen installatie nodig en werkt zo van de stick.

Nog steeds vast?

Geen probleem. Vraag gewoon een coach tijdens de sessie, of post je vraag in de CoderDojo-chat. Geef daarbij de exacte foutmelding mee (kopieer en plak de tekst uit Thonny), dan kunnen we je sneller helpen.