UV est le nouveau gestionnaire de projets Python dont nous avons déjà parlé, et que de plus en plus d’équipes de développeurs adoptent, comme alternative notamment à Pyenv et/ou Poetry.
Parmi les commandes que cet outil propose, trois reviennent souvent dans les discussions : uv tool install, uv add, uv pip install.
Voici une explication claire et directe pour savoir lequel utiliser selon votre objectif.

uv add — Ajouter et suivre les dépendances d’un projet

uv add est la commande à utiliser lorsque l’on installe un package utilisé par un projet (typiquement une bibliothèque), c’est-à-dire une des dépendances du projet.

Par exemple :

uv add httpx

Dans cet exemple, la commande :

– installe le package (httpx) dans l’environnement virtuel du projet,
– met à jour le fichier pyproject.toml,
– met à jour le fichier uv.lock (un lockfile portable et reproductible).

C’est la bonne façon de gérer les dépendances que le code de notre projet Python importe. L’environnement virtuel du projet reste propre, stable et reproductible.

Notez que l’on peut désinstaller / retirer une dépendance avec la commande « uv remove ».

uv pip install — Installer rapidement sans suivre la dépendance

Cette version moderne et rapide de la commande « pip install » est à utiliser quand l’on veut installer quelque chose rapidement, sans l’ajouter à la liste officielle des dépendances du projet.

Par exemple :

uv pip install pandas

Ici, la commande :

– installe le package dans l’environnement actif,
– n’ajoute pas la dépendance dans le fichier pyproject.toml,
– ne met pas à jour le uv.lock.

Contrairement au cas avec « uv add », cette installation est non suivie et hors de la configuration officielle du projet.

Compte-tenu de son fonctionnement, « uv pip install » n’est pas recommandé pour l’essentiel du workflow de développement d’un projet, mais peut être utile de temps en temps lorsque l’on teste rapidement un package avant de décider de l’inclure comme dépendance.

uv tool install — Installer des outils dans des environnements isolés

Cette commande sert à installer des outils CLI (linters, formatters, utilitaires…) dans des environnements
isolés, séparés de votre projet.

Par exemple, installons puis utilisons Ruff :

uv tool install ruff
ruff check .

Ici, UV :

– crée un environnement dédié uniquement à cet outil,
– installe l’outil dans cet environnement,
– le rend accessible globalement,
– évite toute pollution ou conflit avec les dépendances du projet en cours.

Ainsi on peut mettre à jour ou rétrograder un outil sans risquer de casser le projet.

Quel choix faire ?

Avant d’installer quoi que ce soit avec UV, cela aide de se poser ces deux questions :

1. Est-ce un outil ou une bibliothèque (ou une dépendance spécifique à un projet) ? S’il s’agit d’un outil, utilisez « uv tool install ». Sinon, utilisez « uv add » ou « uv pip install ».
2. Dans le cas d’une dépendance, faut-il la suivre ? Si oui, utilisez « uv add ». Sinon utilisez « uv pip install ».

Enfin, « uv pip install » est un moyen de migrer en douceur son workflow vers les pratiques d’UV, quand on vient de commencer à s’en servir, mais avec le temps vous devriez rarement l’utiliser, au vu des avantages de « uv add » combiné à « uv remove ».