Résolution de problèmes

Ton code ne fonctionne pas et tu ne sais pas pourquoi ? Pas de panique : presque chaque problème a une solution simple. Parcours la liste ci-dessous et regarde si ton message d’erreur y figure.

Pgzero ou pygame ne peut pas être installé

Tu vois une erreur comme No matching distribution found ou Package not found quand tu installes pgzero ou pygame.

Cause : tu utilises une version de Python pour laquelle la bibliothèque n’a pas encore de version prête à l’emploi. Ça arrive avec Python 3.16 ou plus, et avec l’ancien pygame sur Python 3.14 et 3.15. Utilise Python 3.13, 3.14 ou 3.15 et la version communautaire pygame-ce au lieu de pygame.

Ubuntu 26.04 a Python 3.14 par défaut. Le script d’installation en un clic règle ça automatiquement :

  • Un Python 3.13, 3.14 ou 3.15 existant est utilisé ; s’il n’y en a pas, Python 3.14 est installé (via le PPA deadsnakes, ppa:deadsnakes/ppa, si apt n’a pas cette version)
  • Thonny est détecté via PATH, snap, pip ou flatpak
  • Si Thonny est installé en snap, la configuration est écrite dans le bon dossier (~/snap/thonny/current/.config/Thonny/)
  • Si apt install thonny ne marche pas, le script essaie pip install --user thonny

Solution : utilise Python 3.13, 3.14 ou 3.15 comme interpréteur actif :

  • Thonny : voir Installer Thonny + Pgzero → Vérifier la version de Python.
  • VS Code : recrée ton environnement avec uv venv --python 3.14.
  • PyCharm : crée un nouvel interpréteur et sélectionne Python 3.14 dans Base interpreter.

pgzrun: command not found

Ça veut dire que Pgzero n’est pas installé, ou que tu utilises une mauvaise version de Python.

Solution : ouvre Thonny, va dans Tools → Manage Packages, cherche pgzero et clique sur Install. Redémarre Thonny ensuite et réessaie.

ModuleNotFoundError: No module named 'pygame'

Python ne trouve pas la bibliothèque pygame. C’est presque toujours parce que Thonny utilise le mauvais interpréteur Python.

Solution : regarde en bas à droite dans la barre d’état de Thonny quel interpréteur est actif. Choisis le même interpréteur que celui utilisé pendant l’installation. Réinstalle ensuite pygame-ce via Tools → Manage Packages.

La fenêtre s’ouvre et se ferme tout de suite

La fenêtre du programme apparaît une seconde puis disparaît.

  • Pgzero : il te faut WIDTH et HEIGHT comme variables séparées en haut de ton fichier, en dehors de toute fonction. Sans ces variables, Pgzero ne sait pas quelle taille la fenêtre doit avoir et s’arrête tout de suite.
  • Pygame : il te faut une boucle d’événements qui appelle pygame.event.get() à chaque frame. Sans cet appel, la fenêtre se fige et le système d’exploitation la ferme.

Les sons ne font rien

Tu appelles sounds.jump.play() mais on n’entend rien.

Vérifie ceci :

  1. Y a-t-il un dossier sounds/ à côté de ton main.py ? Le dossier doit être exactement au même endroit.
  2. Les noms de fichiers sont-ils en minuscules et utilises-tu des underscores au lieu d’espaces ? Par exemple jump.wav, pas Jump.wav ni jump sound.wav.
  3. Pgzero n’accepte que des fichiers .wav dans le dossier sounds/. Pgzero les charge automatiquement, donc tu n’as rien à importer toi-même.

Le son ne marche pas dans pygame (session 5 et plus)

Tu utilises pygame.mixer.Sound(...) mais on n’entend rien, sans message d’erreur ; le jeu démarre simplement sans son.

Cause : Python cherche le fichier audio relativement au dossier depuis lequel tu démarres le script, pas au dossier où se trouve main.py. Si tu ouvres VS Code depuis la racine du projet et que ton script est dans un sous-dossier, Python cherche sounds/hit.wav dans la racine du projet et ne le trouve pas. Le try/except du starter attrape cette erreur en silence.

Solution : utilise __file__ pour rendre le chemin absolu :

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

__file__ est toujours le chemin vers main.py lui-même, peu importe d’où tu démarres le script. Les fichiers de départ à partir de la session 5 le font déjà. Ajoute les deux lignes juste au-dessus du chargement des sons si ton propre jeu ne le fait pas encore.

Les images ne s’affichent pas

Ton actor ou ton arrière-plan n’est pas visible.

Vérifie ceci :

  1. Y a-t-il un dossier images/ à côté de ton main.py ?
  2. Tous les noms de fichiers sont-ils en minuscules ? player.png fonctionne ; Player.png non.
  3. Utilise de préférence des fichiers .png, car ce sont eux qui marchent le plus sûrement avec Pgzero.

KeyError avec une image

Tu obtiens un KeyError quand tu crées un Actor ou charges une image.

Cause : le nom que tu passes doit correspondre exactement au nom du fichier, sans extension. Actor('basket') cherche images/basket.png. Une faute de frappe ou une majuscule en trop suffit à provoquer l’erreur.

Solution : vérifie le nom du fichier dans le dossier images/ et assure-toi qu’il correspond exactement à ce que tu as écrit dans le code.

Chromebook ou pas de droits d’installation

Tu ne peux pas installer Thonny ou Pgzero parce que tu n’as pas les droits d’administrateur sur l’ordinateur.

Solution : travaille avec quelqu’un qui a déjà Thonny, parce que le pair-programming est de toute façon une bonne idée ! À la maison, tu peux continuer avec la version pygbag : elle fait tourner ton projet Pygame directement dans le navigateur, sans installation.

L’antivirus bloque l’installation

Ta tentative d’installation est interrompue ou bloquée par un antivirus.

Solution : désactive temporairement l’antivirus pendant l’installation, ou demande à un coach de mettre une version portable de Thonny sur une clé USB. Cette version n’a pas besoin d’installation et fonctionne directement depuis la clé.

Toujours bloqué ?

Pas de problème. Demande simplement à un coach pendant la session, ou poste ta question dans le chat CoderDojo. Donne le message d’erreur exact (copie et colle le texte de Thonny), on pourra t’aider plus vite.