Gérer les dépendances Python avec uv

uv gère les dépendances et l'environnement virtuel d'un projet Python. Tout repose sur trois fichiers, toujours dans le même ordre :

pyproject.toml ──uv lock──▶ uv.lock ──uv sync──▶ .venv/
ce qu'on veut              versions exactes     ce qui est installé
(plages >=, <)

Fichier	Rôle	Dans git
pyproject.toml	Dépendances voulues, avec des plages de versions	Oui
uv.lock	Versions exactes résolues, pour toutes les plateformes	Oui
.venv/	Environnement installé sur la machine	Non

Règle à retenir

On commite toujours pyproject.toml et uv.lock ensemble.

Sur le poste de développement

Étape	Commande
Ajouter une dépendance	uv add httpx
Ajouter une dépendance de dev	uv add --dev pytest
Retirer une dépendance	uv remove httpx
Après un git pull	uv sync
pyproject.toml modifié à la main	uv lock, puis uv sync
Mettre à jour un paquet	uv lock --upgrade-package httpx
Tout mettre à jour	uv lock --upgrade
Lancer une commande	uv run pytest
Avant de commiter	uv lock --check

uv add et uv remove mettent à jour les trois étages d'un coup. uv run resynchronise le .venv avant de lancer la commande.

Si le projet déclare ses outils de dev en dépendances optionnelles ([project.optional-dependencies]) plutôt qu'en groupe de dev, on écrit uv add --optional dev pytest et uv sync --extra dev.

En intégration continue

bash

uv sync --locked
uv run pytest

Sur le serveur

bash

uv cache prune --ci
uv sync --locked --no-dev

uv cache prune --ci vide le cache des paquets téléchargés. Sans lui, le cache garde chaque version installée et finit par remplir le disque.

--locked ou --frozen

• --locked installe dans le .venv les paquets aux versions exactes listées dans uv.lock, et échoue s'il ne correspond plus à pyproject.toml. C'est l'option à utiliser en CI et en production : un pyproject.toml commité sans son lock est détecté.
• --frozen installe aussi les versions de uv.lock, mais sans vérifier qu'il correspond encore à pyproject.toml. À éviter, sauf cas particulier.