Gestion des versions et des paquets en Python

1. Le modèle mental indispensable

Les difficultés viennent souvent du fait que l’on confond plusieurs éléments indépendants :

1. la version de Python ;
2. l’interpréteur Python réellement exécuté ;
3. l’environnement Python actif ;
4. l’outil d’installation des paquets ;
5. les versions des bibliothèques ;
6. les formats de distribution comme les wheels ;
7. le système d’exploitation et l’architecture du processeur.

Lorsqu’on exécute :

pip install pandas

la vraie question n’est pas seulement :

Quelle version de pandas sera installée ?

Il faut aussi demander :

Quel pip est exécuté, à quel interpréteur Python appartient-il, dans quel environnement installe-t-il, et existe-t-il un fichier binaire compatible avec mon système ?

Partie 1 — Une installation Python n’est pas un simple exécutable

2. Qu’est-ce qu’une version de Python ?

Une installation Python contient notamment :

• un interpréteur ;
• la bibliothèque standard ;
• des fichiers de configuration ;
• un répertoire destiné aux paquets externes ;
• éventuellement pip ;
• parfois des bibliothèques natives ;
• des en-têtes C pour compiler des extensions.

L’exécutable peut porter différents noms :

python
python3
python3.11
python3.12
python.exe

Sous Windows, on peut également disposer du lanceur Python :

py

Le lanceur py est particulièrement utile lorsque plusieurs versions sont installées.

Exemples :

py --list
py -3.11 --version
py -3.12 --version
py -3.11 script.py

Une version Python est constituée de l’interpréteur, de la bibliothèque standard et de ses fichiers associés.

3. Version majeure, mineure et corrective

Dans :

Python 3.12.7

on distingue :

3      version majeure
12     version mineure
7      version corrective

Les incompatibilités de paquets concernent principalement la version mineure.

Par exemple :

Python 3.10
Python 3.11
Python 3.12
Python 3.13

ne doivent pas être considérés comme quatre mises à jour parfaitement interchangeables.

Une bibliothèque peut déclarer :

Requires-Python >=3.10,<3.13

Elle acceptera Python 3.10, 3.11 et 3.12, mais refusera Python 3.13.

À l’inverse, les versions correctives sont normalement compatibles entre elles :

3.12.1
3.12.7
3.12.10

Un environnement virtuel créé avec Python 3.12.1 reste généralement utilisable avec les correctifs de la branche 3.12, même s’il est souvent préférable de le recréer après un changement important de l’installation système.

4. CPython n’est pas l’unique implémentation de Python

L’implémentation utilisée dans l’immense majorité des projets est CPython.

Il existe cependant d’autres implémentations :

• PyPy ;
• GraalPy ;
• MicroPython ;
• Jython ;
• IronPython.

Lorsqu’une wheel contient le tag :

cp312

cela signifie généralement :

CPython 3.12

Une wheel cp312 ne vise pas nécessairement PyPy 3.12.

Vérification :

python -c "import platform; print(platform.python_implementation())"

Résultat typique :

CPython

Partie 2 — Pourquoi plusieurs commandes Python coexistent

5. Le problème du PATH

Lorsque l’on tape :

python

le système cherche un exécutable dans les répertoires inscrits dans la variable PATH.

Sous Windows :

where python
where pip

Sous Linux ou macOS :

which python
which python3
which pip
type -a python
type -a pip

Il est fréquent d’obtenir plusieurs installations :

C:\Users\yvon\AppData\Local\Programs\Python\Python311\python.exe
C:\Users\yvon\AppData\Local\Programs\Python\Python312\python.exe
C:\Windows\py.exe

Le premier chemin trouvé dans PATH est généralement utilisé.

Ainsi, il est possible que :

python

désigne Python 3.12, alors que :

pip

appartienne à Python 3.11.

C’est l’une des causes les plus fréquentes de ce problème :

pip install requests

réussit, mais :

import requests

échoue avec :

ModuleNotFoundError: No module named 'requests'

6. La règle d’or : utiliser python -m pip

Au lieu de :

pip install requests

utiliser :

python -m pip install requests

Ou, sous Windows :

py -3.12 -m pip install requests

Cette syntaxe signifie :

Exécute le module pip avec cet interpréteur Python précis.

Elle garantit que le pip utilisé appartient au Python indiqué.

Commandes de diagnostic :

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

Exemple :

Python 3.12.7
C:\Python312\python.exe
pip 25.x from C:\Python312\Lib\site-packages\pip

Les trois chemins doivent être cohérents.

7. Diagnostic complet de l’interpréteur actif

Cette commande est particulièrement utile :

python -c "import sys, platform; print('Executable:', sys.executable); print('Version:', sys.version); print('Prefix:', sys.prefix); print('Base prefix:', sys.base_prefix); print('Architecture:', platform.machine())"

Informations importantes :

sys.executable

Chemin de l’interpréteur exécuté :

import sys
print(sys.executable)

sys.version

Version détaillée :

print(sys.version)

sys.prefix

Racine de l’environnement actif.

sys.base_prefix

Racine de l’installation Python d’origine.

Dans un environnement virtuel :

sys.prefix != sys.base_prefix

Test :

python -c "import sys; print(sys.prefix != sys.base_prefix)"

Résultat :

True

signifie généralement qu’un environnement virtuel est actif.

Partie 3 — Installation globale, utilisateur et virtuelle

8. Les trois emplacements principaux

Un paquet peut être installé :

1. globalement ;
2. dans le répertoire utilisateur ;
3. dans un environnement virtuel.

9. Installation globale

Exemple :

python -m pip install requests

sans environnement virtuel.

Le paquet est installé dans le site-packages associé à l’interpréteur global.

Sous Windows :

C:\Python312\Lib\site-packages

Sous Linux :

/usr/local/lib/python3.12/site-packages

ou :

/usr/lib/python3/dist-packages

Pourquoi l’installation globale est problématique

Deux projets peuvent demander des versions différentes :

Projet A : Django 4.2
Projet B : Django 5.2

Un environnement global ne peut généralement contenir qu’une version de Django pour un même interpréteur.

Installer Django 5.2 pour le projet B peut donc casser le projet A.

Autre problème : sur Linux, le Python global peut être utilisé par le système d’exploitation.

Modifier ses paquets peut casser :

• un gestionnaire de paquets ;
• des scripts d’administration ;
• des outils système ;
• des composants installés par la distribution.

Les distributions modernes peuvent déclarer l’environnement Python système comme « externally managed », afin d’empêcher pip de le modifier directement.

10. Installation utilisateur

Commande :

python -m pip install --user requests

Le paquet est installé dans un répertoire appartenant à l’utilisateur.

Exemple Windows :

C:\Users\yvon\AppData\Roaming\Python\Python312\site-packages

Exemple Linux :

~/.local/lib/python3.12/site-packages

Cette méthode évite les droits administrateur, mais elle n’isole pas les projets.

Tous les projets utilisant ce Python peuvent voir ces paquets.

Elle est donc utile dans certains cas ponctuels, mais elle ne remplace pas un environnement virtuel.

11. Installation dans un environnement virtuel

Un environnement virtuel possède notamment :

• son propre exécutable Python ou un lien vers celui-ci ;
• son propre site-packages ;
• son propre pip ;
• un fichier pyvenv.cfg.

Dans sa forme minimale, un environnement virtuel contient un exécutable ou lien vers Python, un répertoire site-packages et un fichier pyvenv.cfg.

Création :

python -m venv .venv

Le module venv crée l’environnement avec la version de Python utilisée pour lancer la commande.

Ainsi :

python3.11 -m venv .venv

crée un environnement en Python 3.11.

Alors que :

python3.12 -m venv .venv

crée un environnement en Python 3.12.

Un environnement virtuel ne choisit pas lui-même une version de Python.

Il hérite de l’interpréteur qui l’a créé.

Partie 4 — Utilisation correcte de venv

12. Création sous Windows

Avec le lanceur Python :

py -3.12 -m venv .venv

Activation dans PowerShell :

.venv\Scripts\Activate.ps1

Activation dans cmd.exe :

.venv\Scripts\activate.bat

Désactivation :

deactivate

13. Création sous Linux ou macOS

python3.12 -m venv .venv

Activation :

source .venv/bin/activate

Désactivation :

deactivate

14. Ce que fait réellement l’activation

L’activation ne démarre pas une machine virtuelle.

Elle modifie principalement la variable PATH afin que :

python
pip

désignent en priorité les exécutables situés dans .venv.

Sous Windows :

.venv\Scripts\python.exe
.venv\Scripts\pip.exe

Sous Linux :

.venv/bin/python
.venv/bin/pip

Il est possible d’utiliser un environnement virtuel sans l’activer :

Sous Windows :

.venv\Scripts\python.exe script.py
.venv\Scripts\python.exe -m pip install requests

Sous Linux :

.venv/bin/python script.py
.venv/bin/python -m pip install requests

L’activation est donc un confort, pas une obligation technique.

15. Vérifier l’environnement actif

Sous Windows :

where python
python -c "import sys; print(sys.executable)"
python -m pip --version

Sous Linux :

which python
python -c "import sys; print(sys.executable)"
python -m pip --version

Résultat attendu :

...\mon-projet\.venv\Scripts\python.exe

ou :

.../mon-projet/.venv/bin/python

16. Ne jamais versionner .venv

Dans .gitignore :

.venv/
venv/
env/
__pycache__/
*.pyc

Un environnement virtuel :

• contient des chemins absolus ;
• dépend du système d’exploitation ;
• dépend de l’architecture ;
• peut contenir des binaires natifs ;
• peut devenir très volumineux.

Il ne doit donc pas être copié entre machines ni ajouté à Git.

On versionne les fichiers décrivant les dépendances, pas l’environnement lui-même.

17. Recréer un environnement propre

Lorsqu’un environnement devient incohérent, le réparer paquet par paquet est souvent une mauvaise stratégie.

Approche propre :

Sous PowerShell :

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

Sous Linux :

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

Partie 5 — Que fait réellement pip install ?

18. Les grandes étapes

Lorsqu’on lance :

python -m pip install pandas

pip doit notamment :

1. identifier la demande ;
2. lire les métadonnées du projet ;
3. vérifier la version de Python ;
4. résoudre les dépendances ;
5. choisir les versions compatibles ;
6. sélectionner un fichier de distribution ;
7. télécharger une wheel ou une archive source ;
8. éventuellement compiler le paquet ;
9. installer les fichiers ;
10. créer les scripts exécutables ;
11. enregistrer les métadonnées d’installation.

La documentation de pip install décrit notamment les étapes d’identification des exigences, de résolution des dépendances, de construction des wheels puis d’installation.

19. PyPI

PyPI, Python Package Index, est le dépôt public principal de paquets Python. Les auteurs y publient leurs distributions et pip peut y rechercher les fichiers adaptés.

Une page PyPI peut proposer plusieurs fichiers pour une seule version :

package-1.0.0.tar.gz
package-1.0.0-py3-none-any.whl
package-1.0.0-cp312-cp312-win_amd64.whl
package-1.0.0-cp312-cp312-manylinux_2_17_x86_64.whl

Ces fichiers ne sont pas interchangeables.

La raison est que le même paquet doit pouvoir fonctionner dans des contextes très différents. Chaque fichier correspond à un cas précis :

• le fichier .tar.gz est le code source, utilisé quand aucune version précompilée n’est disponible ;
• le fichier py3-none-any.whl est une version pure Python, compatible avec tous les systèmes ;
• les fichiers cp312-... sont des versions compilées pour une version précise de Python (ici CPython 3.12) ;
• les suffixes win_amd64 ou manylinux_2_17_x86_64 indiquent le système d’exploitation et l’architecture.

En résumé, plusieurs versions existent pour garantir que pip puisse installer le bon fichier selon :

• ta version de Python,
• ton système d’exploitation,
• ton architecture matérielle,
• et la présence ou non de code compilé.

C’est ce mécanisme qui permet à un même paquet d’être utilisable sur presque toutes les machines, sans modification manuelle.