Un Python réinstallable sans internet

L’échec que cette leçon prévient

Une analyse s’exécute sur votre portable. Trois mois plus tard, le même script est lancé par quelqu’un d’autre, sur une autre machine, et soit il ne démarre pas, soit — bien pire — il produit un chiffre différent.

Ce n’est généralement pas un défaut de l’analyse. C’est un défaut de l’environnement : une version de pandas différente dont un réglage par défaut a changé, un paquet installé pour un projet qui en a cassé un autre, un Python système que le système d’exploitation a mis à jour sous vos pieds.

Cette leçon vise à faire de l’environnement une chose que vous déclarez, plutôt qu’une chose qui s’accumule.

Ne travaillez pas dans le Python système

macOS et la plupart des distributions Linux livrent un Python que le système d’exploitation utilise pour son propre outillage. Sur un portable de terrain partagé, quelqu’un en a généralement installé un deuxième depuis un site web, et un troisième est arrivé avec une suite bureautique.

Installer des paquets dans l’un d’eux est une mauvaise idée pour une raison précise : le système d’exploitation dépend des versions qu’il a livrées. Mettre pandas à jour pour satisfaire votre script peut casser un utilitaire système, et rien ne vous en avertira.

Les versions récentes de Python refusent désormais purement et simplement :

error: externally-managed-environment

x This environment is externally managed
+-> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

Cette erreur est justifiée et ne doit pas être contournée. Il existe une option pour passer outre. L’utiliser, c’est ainsi qu’un portable finit par devoir être réinstallé entièrement.

Ce qu’est un environnement virtuel

Un environnement virtuel est un répertoire contenant sa propre copie du répertoire de paquets de l’interpréteur. L’activer change l’endroit où python et pip vont chercher. Toute l’idée est là.

python3 -m venv .venv
source .venv/bin/activate       # Windows : .venv\Scripts\activate
python -m pip install pandas

Deux conséquences à intérioriser :

• Par projet, non par machine. Deux analyses exigeant des versions de pandas différentes coexistent sans que l’une sache que l’autre existe.
• Jetable. Si un environnement se retrouve dans un mauvais état, supprimez le répertoire et reconstruisez-le. Rien de précieux n’y réside — ce qui n’est vrai que si vos dépendances sont déclarées ailleurs.

uv, et pourquoi il compte davantage ici qu’ailleurs

pip résout et télécharge les paquets un par un depuis le réseau. Sur une connexion qui tombe, une installation à moitié terminée laisse un environnement qui n’est ni l’ancien ni le nouveau.

uv est un résolveur plus rapide qui produit un fichier de verrouillage : la liste exacte de chaque paquet et de chaque version, y compris ceux dont vos paquets dépendent.

# Installer uv lui-meme, une fois, sur une machine effectivement connectee.
curl -LsSf https://astral.sh/uv/install.sh | sh

uv init muac-analysis
cd muac-analysis
uv add pandas openpyxl
uv run python -c "import pandas; print(pandas.__version__)"

uv add écrit deux fichiers. pyproject.toml consigne ce que vous avez demandé — pandas — et uv.lock consigne ce que vous avez obtenu, jusqu’à la version exacte de chaque dépendance transitive. Versionnez les deux. Le premier est votre intention ; le second est ce qui rend l’installation du trimestre prochain identique à celle-ci.

Sur le portable de terrain :

uv sync                        # lit uv.lock, installe exactement ces versions

conda est l’alternative raisonnable et reste courante dans ce secteur, en particulier lorsqu’une pile géospatiale est en jeu — GDAL s’installe bien plus facilement par conda que par pip. Si votre organisation a déjà standardisé sur conda, utilisez conda ; le principe est identique et seules les commandes changent.

Installer là où il n’y a pas d’internet

C’est la partie que la plupart des tutoriels sautent, et c’est celle qui compte sur un déploiement.

Téléchargez les paquets une fois, sur une machine connectée, en ciblant la plateforme du portable de terrain :

mkdir wheels
uv pip download pandas openpyxl --dest wheels

Copiez le répertoire wheels sur une clé USB avec votre projet, puis sur la machine hors ligne :

uv venv
uv pip install --no-index --find-links wheels pandas openpyxl

--no-index indique à l’installateur de ne pas contacter du tout l’index de paquets, et --find-links le dirige vers le répertoire à la place. L’installation est alors entièrement locale.

Les wheels sont spécifiques à une plateforme. Une wheel téléchargée sous macOS ne s’installera pas sur un portable Windows, et une wheel construite pour Python 3.12 ne s’installera pas dans 3.11. Téléchargez sur une machine correspondant à la cible, ou passez explicitement --python-platform et --python-version.

Épingler aussi la version de Python

Les paquets sont épinglés ; l’interpréteur devrait l’être également. Un script écrit pour 3.12 et exécuté sous 3.9 échoue sur une syntaxe qui n’existait pas encore.

# pyproject.toml
[project]
name = "muac-analysis"
requires-python = ">=3.11"
dependencies = ["pandas>=2.2", "openpyxl>=3.1"]

uv python install 3.12
uv python pin 3.12

Vérifier l’environnement avant de lui faire confiance

Avant d’exécuter une analyse sur une machine que vous n’avez pas configurée, vérifiez que vous êtes bien là où vous le croyez :

import sys
import pandas as pd

print(sys.executable)          # doit se trouver dans .venv, non dans /usr/bin
print(sys.version)
print(pd.__version__)

Si sys.executable vaut /usr/bin/python3, l’environnement n’est pas activé et vous êtes sur le point d’installer dans le Python système. Cette seule ligne a sauvé plus de portables que n’importe quelle documentation.

Pour une analyse dont les chiffres comptent, transformez-la en assertion :

import sys

assert sys.version_info >= (3, 11), f"exige Python 3.11+, execute {sys.version}"

Ce qu’il faut remettre à un collègue

Tout ce qui permet de reconstruire l’environnement, et rien de ce qui a été construit :

À versionner	À ne pas versionner
pyproject.toml	.venv/
uv.lock	wheels/
README.md avec les deux commandes	__pycache__/

Un .gitignore couvrant la colonne de droite fait partie du gabarit de projet de la leçon suivante.

Le README a besoin de deux lignes, non de deux pages :

uv sync
uv run python scripts/indicator_table.py --input data/raw/muac.csv

Ce qui vient ensuite

L’environnement est reproductible. La leçon suivante porte sur le projet qui l’entoure — où vont les données brutes, où vont les sorties, et pourquoi un chemin écrit C:\Users\marie\Bureau\data.csv garantit que le script s’exécutera sur exactement une machine.