Comment mettre en place un projet Python rapide et reproductible avec uv

Quand vous lancez un agent de codage IA comme Claude Code ou Codex sur un projet Python, la moitié des frictions n'a rien à voir avec le modèle. Elle vient de l'environnement : des paquets manquants, la mauvaise version de Python, un virtualenv que l'agent a oublié d'activer, ou un coéquipier pour qui « ça marche sur ma machine ». La solution, c'est un projet reproductible par défaut, et le moyen le plus rapide d'en obtenir un aujourd'hui, c'est uv, la chaîne d'outils Python écrite en Rust par Astral.

uv remplace pip, venv, pip-tools et pyenv par une seule commande rapide, et il écrit un fichier de verrouillage pour que l'arbre de dépendances exact s'installe partout à l'identique. Ce guide vous mène de rien à un projet verrouillé et exécutable en quelques minutes.

Pourquoi l'environnement compte pour un agent

Un agent IA exécute des commandes dans votre shell et lit les erreurs qui en reviennent. Si votre projet n'a aucune dépendance déclarée ni version de Python figée, l'agent doit deviner — et une mauvaise supposition l'entraîne dans une spirale d'installations de paquets au niveau global ou de modifications du mauvais interpréteur. Un projet doté d'un pyproject.toml et d'un uv.lock offre à l'agent une source unique de vérité : il peut lancer uv sync, obtenir les bons paquets et passer à la suite. Vous consacrez votre temps de relecture à la logique, pas à l'archéologie d'environnement.

Installer uv

Sur macOS ou Linux :

curl -LsSf https://astral.sh/uv/install.sh | sh

Sur Windows (PowerShell) :

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv est un binaire unique et autonome, il n'y a donc rien d'autre à configurer.

Démarrer un projet en une seule commande

uv init weather-cli
cd weather-cli

Cela génère un projet fonctionnel : un pyproject.toml pour les métadonnées et les dépendances, un fichier .python-version, un main.py de départ, un README.md et un .gitignore. Vous n'avez pas à créer ni à activer un virtualenv à la main — uv gère un .venv pour vous dès que vous en avez besoin.

Ajouter des dépendances (et pourquoi le fichier de verrouillage compte)

uv add requests

Cela accomplit trois choses à la fois : enregistrer requests dans pyproject.toml, résoudre l'arbre de dépendances complet et écrire uv.lock avec des versions exactes et figées, multiplateformes. Vous pouvez aussi figer une version au moment de l'ajout :

uv add 'requests==2.31.0'

Validez uv.lock dans Git. C'est toute la différence entre « installer la dernière version de requests » (qui dérive avec le temps) et « installer l'arbre exact que nous avons testé ». Lorsque votre agent — ou votre CI, ou un nouveau coéquipier — lance uv sync, il obtient un environnement identique octet pour octet.

Exécuter du code sans rien activer

uv run main.py

uv run s'assure que l'environnement est synchronisé, puis exécute à l'intérieur de celui-ci — fini la danse du source .venv/bin/activate. Cela compte particulièrement pour les agents : chaque appel d'outil part souvent d'un shell neuf, si bien que « activer puis exécuter » échoue fréquemment, alors qu'un simple uv run fonctionne toujours. Vous pouvez encapsuler n'importe quelle commande :

uv run -- pytest -q
uv run -- flask run -p 3000

Figer une version de Python pour que l'agent et la CI s'accordent

uv python pin 3.12

Cela écrit la version dans .python-version, et uv téléchargera et utilisera cet interpréteur automatiquement — aucun Python système requis. Désormais, la version sur laquelle vous développez est celle qu'utilisent votre agent, vos coéquipiers et votre CI.

Un court exemple concret

Supposons que vous demandiez à un agent d'« ajouter une commande qui récupère la météo du jour ». Avec uv en place, toute la boucle est limpide :

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# l'agent modifie main.py pour appeler une API...
uv run main.py

L'agent n'a jamais à se demander quel interpréteur est actif ni si requests est installé — ces faits sont déclarés dans des fichiers qu'il peut lire. S'il introduit une nouvelle dépendance, il lance uv add et le fichier de verrouillage se met à jour. Si quelque chose casse dans la CI, uv sync reproduit l'environnement exact en local pour que vous puissiez déboguer.

Où va uv

uv et ses outils frères ruff (linter/formateur) et ty (vérificateur de types) sont largement adoptés — uv à lui seul dépasse les 100 millions de téléchargements par mois. En mars 2026, OpenAI a convenu de racheter Astral, l'entreprise qui les développe, afin d'intégrer la chaîne d'outils à sa plateforme Codex, tout en s'engageant à maintenir ces outils sous licence MIT en open source (OpenAI, Simon Willison). Pour l'instant, l'enseignement pratique reste inchangé : uv est le chemin le plus rapide vers un projet Python sur lequel votre agent IA peut bâtir sans deviner.

Aide-mémoire

Tâche	Commande
Créer un projet	uv init <name>
Ajouter une dépendance	uv add <package>
Figer Python	uv python pin 3.12
Exécuter du code	uv run <file or command>
Reproduire l'environnement	uv sync
Mettre à jour le fichier de verrouillage	uv lock --upgrade-package <pkg>