Environnements virtuels (venv)

Imagine : tu pars en camp et tu dois préparer ton sac à dos. Pour un camp de sport, tu y mets d’autres choses que pour un camp de musique. Si tu mélanges tout, tu ne retrouves plus rien.

C’est pareil avec les projets Python. Chaque projet a besoin de son propre « sac à dos » : un environnement virtuel avec exactement ce qu’il faut dedans.

Qu’est-ce qu’un environnement virtuel ?

Un environnement virtuel (en abrégé venv, prononce : « ven-vee ») est un dossier séparé sur ton ordinateur qui contient Python et tous les paquets supplémentaires d’un seul projet.

Suppose que tu as deux projets :

Projet A utilise Pygame version 2.5
Projet B utilise Pygame version 2.6

Sans environnements virtuels, tu ne pourrais installer qu’une seule version de Pygame sur ton ordinateur. L’un des projets ne fonctionnerait alors plus. Avec des environnements virtuels, chaque projet a sa propre boîte fermée avec la bonne version dedans. Ils ne se gênent pas.

Métaphore : un environnement virtuel, c’est comme un sac à dos personnel par projet. Tu y mets exactement ce dont ce projet a besoin, et les sacs à dos sont rangés séparément dans l’armoire.

Pourquoi les utiliser ?

Pas de conflit entre projets. Les versions 2.5 et 2.6 peuvent exister toutes les deux, chacune dans son propre environnement.
Partager est facile. Si tu partages ton projet avec un ami (ou une amie), tu ne dois pas envoyer tous les paquets. Ton ami (ou amie) crée simplement son propre environnement virtuel et installe les mêmes paquets.
Ton ordinateur reste rangé. Tu n’installes rien « comme ça » sur tout ton ordinateur. Tout reste bien dans le sac à dos du bon projet.

Comment créer un environnement virtuel avec `uv`

uv est le gestionnaire de paquets Python qu’on utilise à la CoderDojo. Il peut créer et gérer des environnements virtuels.

Étape 1 : ouvrir un terminal

Windows : appuie sur ⊞ Windows, tape cmd et ouvre “Invite de commandes” (ou utilise PowerShell).
macOS / Linux : ouvre “Terminal”.

Étape 2 : aller dans le dossier de ton projet

cd chemin/vers/ton/dossier-de-projet

Astuce

Remplace chemin/vers/ton/dossier-de-projet par le vrai chemin, par exemple cd Bureau/mon-jeu.

Étape 3 : créer l’environnement virtuel

uv venv

uv crée maintenant un petit dossier .venv dans ton dossier de projet. Il contient une installation Python séparée.

Tu veux utiliser une version précise de Python ? C’est possible aussi :

uv venv --python 3.14

Pourquoi faire ça ? Pour être sûr d’utiliser une version de Python qui fonctionne avec nos bibliothèques de jeux. Choisis 3.13, 3.14 ou 3.15.

Étape 4 : activer l’environnement virtuel

L’environnement existe, mais tu dois encore l’“allumer”. C’est ce qu’on appelle activer.

Windows (Invite de commandes ou PowerShell) :

.venv\Scripts\activate

macOS / Linux :

source .venv/bin/activate

Après l’activation, tu vois (.venv) apparaître à gauche dans ton terminal. C’est le signe que tu travailles maintenant dans ton environnement virtuel.

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

Étape 5 : installer des paquets

Maintenant que ton environnement est actif, tu peux installer des paquets. Ils arrivent uniquement dans ce seul sac à dos :

uv add pgzero pygame-ce

Remarque

pygame-ce est la version communautaire de Pygame et fonctionne aussi sur Python 3.14 et 3.15. Pgzero demande cependant encore l’ancien pygame.

Mets donc aussi cette ligne dans ton pyproject.toml :

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

Étape 6 : désactiver

Tu as fini de programmer ? Tape simplement :

deactivate

Le signe (.venv) disparaît et tu retravailles avec le Python normal de ton ordinateur.

À quoi faire attention ?

⚠️ N’oublie pas d’activer l’environnement

L’erreur la plus fréquente : tu ouvres un nouveau terminal et tu oublies d’activer l’environnement virtuel. Python se plaint alors de ne pas trouver les paquets, alors que tu les as bien installés.

Solution : active toujours d’abord avec .venv\Scripts\activate (Windows) ou source .venv/bin/activate (macOS/Linux) avant de lancer ton programme.

⚠️ Mets `.venv` dans `.gitignore`

Le dossier .venv est gros (parfois des centaines de Mo). Tu ne dois pas le partager via Git ou GitHub. Mets .venv dans ton fichier .gitignore, pour que Git l’ignore :

.venv/

Ton ami (ou amie) crée simplement son propre .venv avec uv venv et installe les mêmes paquets via le fichier pyproject.toml qui, lui, est bien dans Git.

⚠️ Utilise `uv run` comme raccourci

Pas envie d’activer et de désactiver à chaque fois ? uv a un raccourci pratique :

uv run python main.py

Il exécute python main.py à l’intérieur de l’environnement virtuel, même s’il n’est pas activé. uv comprend tout seul quel environnement va avec le projet.

⚠️ Terminaux différents, environnements différents

Si tu actives l’environnement dans un terminal, il n’est pas actif automatiquement dans un autre terminal. Tu dois activer séparément chaque terminal où tu veux utiliser l’environnement.

En résumé

Action	Commande (Windows)	Commande (macOS/Linux)
Créer	`uv venv`	`uv venv`
Activer	`.venv\Scripts\activate`	`source .venv/bin/activate`
Désactiver	`deactivate`	`deactivate`
Raccourci	`uv run python main.py`	`uv run python main.py`

La règle d’or : tu vois (.venv) dans ton terminal ? Alors tout va bien. Tu ne le vois pas ? Active d’abord, programme ensuite.

Quelle est la différence avec virtualenv et pip ? Avant uv, il existait déjà d’autres outils comme virtualenv (pour les environnements) et pip (pour les paquets). Avec eux, tu pouvais faire la même chose, mais tu devais utiliser deux commandes séparées et ça marchait beaucoup plus lentement. uv fait tout en une fois, est bien plus rapide, et est bien plus simple pour les débutants. À la CoderDojo, on préfère donc uv.

Tu as des problèmes avec ton environnement virtuel ? Va voir Résolution de problèmes pour les erreurs fréquentes.