Isoler les dépendances

Ce que vous saurez faire

Donnez au projet ticket-cleaner son propre environnement Python, installez-y un paquet et notez les versions exactes. Le projet fonctionnera ainsi de la même façon le mois prochain et sur l’ordinateur d’une autre personne.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 35 minutes

Ce que vous devez savoir

• Ce qu’est l’interpréteur et comment vérifier quel Python s’exécute, dans Installer et vérifier Python.
• Le répertoire de travail, dans Les fichiers et le terminal.

Ce qu’il vous faut sur votre ordinateur

• Python 3.12 ou plus récent, qui s’exécute quand vous tapez python3 (python sur Windows). Vous l’avez installé dans Installer et vérifier Python : étape 1. Si le mauvais Python s’exécute, suivez l’erreur courante « Le mauvais Python s’exécute » sur cette page.
• first_run.py dans ~/projects/ticket-cleaner. Vous l’avez créé dans Installer et vérifier Python : exercices guidés. S’il manque, recréez-le à partir de l’exemple détaillé.
• VS Code avec l’extension Python, présenté dans Installer et vérifier Python : étape 3. Un autre éditeur de code convient aussi.
• Une connexion Internet. Vous téléchargez environ 1 Mo de paquets.

Testé avec Python 3.14 sur macOS (pip 26.1), Windows dans PowerShell et Ubuntu 26.04 (pip 25.1).

Les paquets et pourquoi chaque projet a besoin des siens

Python comprend beaucoup de code prêt à utiliser. Pour d’autres tâches, vous utilisez des paquets : du code que d’autres personnes ont écrit et publié. Par exemple, le paquet httpx envoie des requêtes à des sites Web, et le paquet pytest exécute des tests. Vous utiliserez les deux plus tard dans ce cours. La plupart des paquets viennent du Python Package Index (PyPI). Vous les installez avec un outil appelé pip.

Un paquet dont votre projet a besoin est une dépendance du projet. Les dépendances causent deux problèmes quand tous les projets partagent un seul Python :

• Les versions entrent en conflit. Un ancien projet a besoin de httpx 0.27, et un nouveau projet a besoin de 0.28. Un seul Python ne peut contenir qu’une version à la fois.
• La liste se perd. Après quelques mois, personne ne sait quels paquets ce projet utilise et lesquels appartiennent aux autres projets. Un nouveau membre de l’équipe ne peut pas le configurer.

Un environnement virtuel règle les deux problèmes. C’est un dossier dans votre projet, généralement appelé .venv. Il possède son propre lien vers l’interpréteur et son propre emplacement pour les paquets. Les paquets que vous y installez sont visibles seulement dans ce projet. Le Python que vous avez installé dans la leçon précédente ne change pas.

L'éditeur et le terminal doivent tous deux utiliser l'interpréteur dans .venv. Le code trouve alors les paquets installés pour ce projet.

Description textuelle du diagramme

Le terminal exécute python first_run.py. Comme l’environnement est activé, python désigne l’interpréteur dans .venv. Cet interpréteur lit le script dans le dossier du projet. Quand le script importe un paquet, il le cherche dans .venv. L’éditeur possède son propre réglage d’interpréteur (ligne pointillée), qui doit pointer vers le même .venv. Si le terminal ou l’éditeur utilise un autre interpréteur, il ne trouve pas les paquets dans .venv.

Pour utiliser un environnement dans un terminal, vous l’activez. L’activation modifie ce terminal pour que la commande python désigne l’interpréteur dans .venv. L’environnement reste actif jusqu’à ce que vous fermiez le terminal ou exécutiez deactivate. L’invite du terminal commence par (.venv) pendant qu’il est actif.

Exemple détaillé : créer et utiliser un environnement

Amira crée un environnement pour ticket-cleaner. La partie -m venv indique à Python d’exécuter son outil intégré venv. Le dernier argument est le nom du dossier à créer.

macOS

Terminal

cd ~/projects/ticket-cleaner
python3 -m venv .venv
source .venv/bin/activate

Windows

PowerShell

cd ~/projects/ticket-cleaner
python -m venv .venv
.venv\Scripts\Activate.ps1

Linux

Terminal

cd ~/projects/ticket-cleaner
python3 -m venv .venv
source .venv/bin/activate

L’invite commence maintenant par (.venv). À partir de là, elle tape python sur chaque système, car l’activation fait pointer python vers l’environnement. Elle vérifie quel interpréteur s’exécute :

Terminal

python -c "import sys; print(sys.executable)"

Output (macOS)

/Users/amira/projects/ticket-cleaner/.venv/bin/python

Le chemin se trouve dans le dossier du projet. Sur Windows, il se termine par ticket-cleaner\.venv\Scripts\python.exe.

Ensuite, elle installe une version exacte de httpx. == signifie « exactement cette version ». Elle exécute pip avec l’interpréteur au moyen de python -m pip. Le paquet va donc dans l’environnement de cet interpréteur, et nulle part ailleurs :

Terminal

python -m pip install httpx==0.28.1

Output (last line)

Successfully installed anyio-4.15.1 certifi-2026.7.22 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.20 typing_extensions-4.16.0

Elle a demandé un paquet, et pip en a installé sept. httpx possède ses propres dépendances, et pip les a aussi installées. Si pip affiche aussi un avis indiquant qu’une nouvelle version de pip est disponible, elle peut l’ignorer.

Pour voir la différence, elle quitte l’environnement et essaie la même importation avec le Python de l’ordinateur :

Terminal

deactivate
python3 -c "import httpx"

Sortie

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import httpx
ModuleNotFoundError: No module named 'httpx'

C’est l’isolation qui fonctionne. httpx existe seulement dans .venv. Elle active de nouveau l’environnement avant de continuer.

Noter les versions

Amira note les besoins du projet pour qu’une autre personne, ou elle-même le mois prochain, puisse recréer le même environnement. Elle utilise deux fichiers :

Fichier	Contenu	Qui l’écrit
requirements.txt	Les paquets que le projet utilise directement, avec les versions qu’elle a choisies.	Vous, à la main.
requirements-lock.txt	Chaque paquet de l’environnement, avec sa version exacte, y compris les dépendances des dépendances.	pip, avec pip freeze.

Dans VS Code, elle crée requirements.txt avec une seule ligne :

requirements.txt

httpx==0.28.1

Ensuite, elle crée le fichier de verrouillage. Le signe > envoie la sortie de la commande dans un fichier plutôt qu’à l’écran :

Terminal

python -m pip freeze > requirements-lock.txt

requirements-lock.txt

anyio==4.15.1
certifi==2026.7.22
h11==0.16.0
httpcore==1.0.9
httpx==0.28.1
idna==3.20
typing_extensions==4.16.0

Pourquoi les deux? requirements.txt est court et montre vos décisions. Quand vous voulez une version plus récente de httpx, vous y modifiez une ligne. Le fichier de verrouillage montre exactement ce qui a été installé. Un nouvel environnement reçoit ainsi les mêmes versions des sept paquets, pas seulement de httpx. Vos versions peuvent être plus récentes que celles-ci. C’est pourquoi vous devez les noter.

Remarque

Des outils plus récents, comme uv, et un format de fichier de verrouillage plus récent, pylock.toml, offrent davantage de fonctions. Ils font le même travail. La méthode à deux fichiers de cette leçon utilise seulement Python et pip, donc elle fonctionne partout. L’idée reste la même dans chaque outil : listez ce qu’il vous faut et verrouillez ce que vous avez obtenu.

Recréer l’environnement à partir de zéro

Un environnement peut être supprimé. Il contient des milliers de fichiers que pip peut recréer. Vous ne le copiez donc pas sur un autre ordinateur et ne l’enregistrez pas dans Git. Vous conservez le fichier de verrouillage. Pour prouver que ce fichier fonctionne, Amira supprime l’environnement et le recrée.

Attention

La commande de suppression efface le dossier et tout son contenu, sans passer par la corbeille. Vérifiez que vous êtes dans le dossier ticket-cleaner avant de l’exécuter, et tapez .venv exactement.

macOS

Terminal

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-lock.txt

Windows

PowerShell

deactivate
Remove-Item -Recurse -Force .venv
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements-lock.txt

Linux

Terminal

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-lock.txt

L’option -r signifie « lire la liste des paquets dans ce fichier ». pip installe les sept mêmes versions. C’est aussi votre réinitialisation : si un environnement ne fonctionne plus correctement, supprimez-le et recréez-le à partir du fichier de verrouillage.

Si vous utilisez Git (voir L’essentiel de Git et du développement en équipe), ajoutez un fichier .gitignore au projet. Inscrivez-y la ligne .venv/. Git ne suit alors pas l’environnement. Vous faites un commit (enregistrement des changements) de requirements.txt et de requirements-lock.txt.

Indiquer à l’éditeur quel interpréteur utiliser

VS Code exécute et vérifie votre code avec son propre réglage d’interpréteur. Choisissez l’environnement pour que l’éditeur et le terminal utilisent le même interpréteur.

1. Dans VS Code, ouvrez le dossier ticket-cleaner.
2. Appuyez sur Ctrl+Shift+P (Cmd+Shift+P sur macOS).
3. Tapez Python: Select Interpreter (Python : sélectionner l’interpréteur), puis appuyez sur Enter.
4. Sélectionnez l’entrée qui affiche .venv.
5. Ouvrez un nouveau terminal avec Terminal › New Terminal (Terminal › Nouveau terminal). VS Code active l’environnement pour vous, et l’invite commence par (.venv).

Exercices guidés : configurer ticket-cleaner

Reproduisez l’exemple détaillé sur votre ordinateur.

1. Allez dans le dossier du projet : cd ~/projects/ticket-cleaner.

2. Créez l’environnement : python3 -m venv .venv (python -m venv .venv sur Windows).

3. Activez-le. Sur macOS et Linux, exécutez source .venv/bin/activate. Sur Windows, exécutez .venv\Scripts\Activate.ps1.

   L’invite commence par (.venv). Si Windows affiche une erreur concernant l’exécution des scripts, consultez la deuxième erreur courante ci-dessous.

4. Vérifiez l’interpréteur :

   python -c "import sys; print(sys.executable)"

   Le chemin contient ticket-cleaner et .venv.

5. Installez le paquet : python -m pip install httpx==0.28.1.

   La dernière ligne commence par Successfully installed (installation réussie).

6. Créez requirements.txt avec la ligne httpx==0.28.1.

7. Créez le fichier de verrouillage : python -m pip freeze > requirements-lock.txt.

8. Exécutez de nouveau votre premier script : python first_run.py.

   La ligne Interpreter: (interpréteur) affiche maintenant le chemin dans .venv.

À vous de jouer : un deuxième projet

Créez un deuxième projet, ~/projects/env-practice, avec son propre environnement. Installez-y la version 0.27.2 de httpx. Créez ensuite un script check_httpx.py dans les deux projets :

check_httpx.py

import sys

import httpx

print("Interpreter:", sys.executable)
print("httpx version:", httpx.__version__)

Exécutez le script dans chaque projet, avec l’environnement de ce projet activé. Prédisez d’abord les deux sorties.

Afficher le résultat attendu

Dans env-practice, le script affiche l’interpréteur dans env-practice/.venv et httpx version: 0.27.2 (version de httpx : 0.27.2). Dans ticket-cleaner, il affiche ticket-cleaner/.venv et 0.28.1. Deux versions du même paquet existent sur un ordinateur, et aucun projet n’a d’effet sur l’autre. Pensez à exécuter deactivate avant de passer à l’autre projet, puis activez l’environnement de ce projet.

Erreur courante

No module named … (aucun module nommé…)

Symptôme : vous exécutez un script, et il s’arrête avec cette erreur, même si vous avez installé le paquet :

ModuleNotFoundError: No module named 'httpx'

Cause : le script utilise un autre interpréteur que celui où vous avez installé le paquet. Généralement, l’environnement n’est pas actif dans ce terminal. Un nouveau terminal ne l’active pas, et l’invite n’affiche pas (.venv). Dans VS Code, le bouton Run (exécuter) peut aussi utiliser un autre interpréteur que le terminal.

Solution :

1. Vérifiez l’interpréteur : python -c "import sys; print(sys.executable)".
2. Si le chemin n’est pas dans le .venv de votre projet, activez l’environnement et exécutez de nouveau le script.
3. Si le chemin est correct, le paquet n’est pas dans cet environnement. Installez-le à partir du fichier de verrouillage : python -m pip install -r requirements-lock.txt.
4. Dans VS Code, sélectionnez de nouveau l’interpréteur de .venv (voir plus haut).

Ne corrigez pas cette erreur en installant le paquet avec un autre pip jusqu’à ce que cela fonctionne. Cela place les paquets à plusieurs endroits, et la prochaine erreur sera plus difficile à trouver.

Erreur courante

Running scripts is disabled (l'exécution des scripts est désactivée, Windows)

Symptôme : sur Windows, la commande d’activation affiche une erreur comme celle-ci, et l’invite ne change pas :

.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system.

Cause : PowerShell n’exécute pas les fichiers de script par défaut. La commande d’activation est un fichier de script.

Solution : autorisez les scripts créés sur votre ordinateur, pour votre compte utilisateur seulement. Exécutez ceci une seule fois :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Tapez Y (oui) si PowerShell demande une confirmation, puis exécutez de nouveau .venv\Scripts\Activate.ps1. Si votre employeur gère votre ordinateur, ce réglage peut être verrouillé. Dans ce cas, demandez à votre équipe informatique. Ou ouvrez Command Prompt (invite de commandes) plutôt que PowerShell, et exécutez .venv\Scripts\activate.bat.

error : externally-managed-environment (erreur : environnement géré à l'extérieur)

Sur Linux et avec Python installé par Homebrew sur macOS, pip install s’arrête hors d’un environnement. Il affiche error: externally-managed-environment (erreur : environnement géré à l’extérieur). C’est une protection : les outils du système utilisent ce Python, et pip ne doit pas le modifier. La solution est la méthode de cette leçon. Activez l’environnement de votre projet, puis installez les paquets.

Vérifiez votre compréhension

Vous ouvrez un nouveau terminal, allez dans ticket-cleaner et exécutez python first_run.py. La ligne Interpreter affiche un chemin hors de .venv. Pourquoi, et que faites-vous?

Afficher la réponse

Un nouveau terminal n’active pas l’environnement. python désigne donc le Python de l’ordinateur, ou la commande python n’existe pas sur macOS et Linux. Activez l’environnement avec source .venv/bin/activate (.venv\Scripts\Activate.ps1 sur Windows). Vérifiez que l’invite commence par (.venv), et exécutez de nouveau le script.

Vérifiez votre compréhension

Un collègue vous envoie un projet avec requirements.txt et requirements-lock.txt, mais sans dossier .venv. Manque-t-il quelque chose? Comment le configurez-vous?

Afficher la réponse

Il ne manque rien. On ne partage pas l’environnement, car on peut le recréer. Créez un environnement dans le dossier du projet, activez-le et exécutez python -m pip install -r requirements-lock.txt. Vous obtenez la même version de chaque paquet que votre collègue.

Vérifiez votre compréhension

Vérification du module : dans un nouveau terminal, montrez quel interpréteur et quel environnement sont utilisés dans ticket-cleaner. Désactivez ensuite l'environnement, exécutez check_httpx.py et corrigez l'erreur affichée sans rien installer de nouveau.

Afficher la réponse

Avec l’environnement actif, python -c "import sys; print(sys.executable)" affiche un chemin dans ticket-cleaner/.venv, et l’invite commence par (.venv). Après deactivate, python3 check_httpx.py s’arrête avec ModuleNotFoundError: No module named 'httpx' (erreur de module introuvable : aucun module nommé « httpx »). Le Python de l’ordinateur ne possède pas httpx. La solution est de réactiver l’environnement, pas d’installer httpx ailleurs. Le script affiche alors httpx version: 0.28.1.

Récapitulatif

• Une dépendance est un paquet dont votre projet a besoin. pip installe les paquets depuis PyPI.
• Un environnement virtuel (.venv) donne à un projet ses propres paquets. Activez-le dans chaque nouveau terminal. L’invite affiche (.venv).
• Installez avec python -m pip install name==version pour que le paquet aille dans l’environnement actif.
• requirements.txt liste vos choix. requirements-lock.txt (créé avec pip freeze) note chaque version exacte. Conservez les deux et recréez l’environnement à partir du fichier de verrouillage au besoin.
• Si un module est introuvable, vérifiez sys.executable avant d’installer quoi que ce soit.

Vous pouvez maintenant configurer un projet Python qu’une autre personne peut recréer. Dans le prochain module, vous commencez à écrire du Python : valeurs, collections, conditions et boucles.

Leçon suivante : Les valeurs de base