Vous connaissez certainement la routine par cœur : on installe Python, on crée un environnement virtuel avec python -m venv venv, on l'active, on lance pip install, et pour jongler entre les différentes versions de Python, on ajoute pyenv par-dessus (que je trouve d'ailleurs très pratique).
C'est ce que j'ai toujours fait. Quand je suis passé à uv, j'étais un peu perdu au début tellement j'avais mes habitudes ancrées. D'ailleurs, uv est déjà énormément adopté dans l'écosystème Python. Voyons ensemble pourquoi, et surtout comment l'utiliser.
Qu'est-ce que uv ?
uv est un gestionnaire de paquets et de projets Python, écrit en Rust par Astral, la même équipe derrière le linter ruff. Son objectif est de remplacer à lui seul toute une panoplie d'outils : pip, venv, virtualenv, pyenv, pipx et même poetry avec un seul exécutable.
Son principal argument, c'est sa vitesse : 10 à 100 fois plus rapide que pip. Une installation de dépendances est quasiment instantanée.
Pour vous donner une idée de l'engouement : uv dépasse les 126 millions de téléchargements mensuels en mars 2026. Ce même mois, OpenAI a carrément racheté Astral.
De pip + venv à uv
C'est LA partie la plus importante. Le déclic se fait quand on comprend que uv s'occupe de l'environnement virtuel à votre place. Reprenons un workflow « habituel » :
# 1. On crée un environnement virtuel python -m venv venv # 2. On l'active (et il faut penser à le faire à chaque fois !) source venv/bin/activate # 3. On installe nos paquets pip install requests # 4. On fige les versions à la main pip freeze > requirements.txt # 5. On lance enfin notre code python main.py
Avec uv, on ne crée plus d'environnement virtuel manuellement, on ne l'active plus et on ne fait plus de pip freeze. Tout ça est géré automatiquement en coulisses. Voici la correspondance directe :
Correspondance pip venv et uv
Une fois ces commandes en tête, vous avez compris 80 % de uv.
À noter
Si vous utilisez aussi pyenv pour jongler entre plusieurs versions de Python, sachez que uv le remplace également : pyenv install 3.12 devient uv python install 3.12. On y revient juste après.
Installer uv
uv est autonome : il n'a pas besoin que Python soit installé au préalable pour fonctionner.
Sur macOS et Linux :
curl -LsSf https://astral.sh/uv/install.sh | sh
Sur Windows (via PowerShell) :
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
À noter
Pour les utilisateurs de macOS, vous pouvez installer uv en passant par Homebrew via la commande brew install uv.
Vous trouverez les différentes façons d'installer uv sur cette page.
Une fois l'installation terminée, pour vérifier que tout fonctionne :
uv --version
À noter
Comme uv est indépendant de Python, c'est lui qui se chargera ensuite de télécharger les versions de Python dont vous avez besoin. Et quand une nouvelle version de uv sort, un simple uv self update suffit à le mettre à jour. Et si vous êtes passé par Homebrew : brew update && brew upgrade.
Créer son premier projet
Pour créer un projet, une seule commande suffit :
uv init patrick cd patrick
uv génère l'arborescence suivante :
. ├── .git/ ├── .gitignore ├── .python-version ├── README.md ├── main.py └── pyproject.toml
Le fichier main.py contient déjà un petit programme. Lançons-le :
uv run main.py # Affiche : Hello from patrick!
Il vient de se passer plusieurs choses. uv a créé l'environnement virtuel (.venv), installé les dépendances nécessaires, généré un fichier uv.lock et exécuté le code dans cet environnement.
Vous devez avoir :
. ├── .git/ ├── .gitignore ├── .python-version ├── .venv/ ├── README.md ├── main.py ├── pyproject.toml └── uv.lock
Regardons les fichiers importants :
-
pyproject.toml: le fichier standard de l'écosystème Python moderne. Il contient les métadonnées de votre projet -
.python-version: il indique à uv quelle version de Python utiliser pour ce projet -
.venv: votre environnement virtuel où sont installées les dépendances du projet -
uv.lock: le fichier de verrouillage. Il liste les versions exactes de toutes vos dépendances
À noter
pyproject.toml et uv.lock gèrent tous les deux vos dépendances, mais pas au même niveau. pyproject.toml impose une contrainte large du type « ce projet a besoin d'au moins la version 2.32.4 de requests ». uv.lock fige la version exacte de requests réellement installée.
Gérer ses dépendances
Pour ajouter une dépendance, on utilise uv add. Pas besoin (ou plus besoin) d'activer quoi que ce soit :
uv add requests
Cette commande met à jour trois fichiers : pyproject.toml, .venv et uv.lock. Il est aussi possible d'installer une version particulière :
uv add 'requests==2.31.0'
Pour vos outils de développement (tests, linter, etc.), on les sépare des dépendances de production avec --dev :
uv add --dev pytest ruff
dev est un groupe de dépendances déjà reconnu par uv. pytest et ruff sont rangés dans une table à part de votre pyproject.toml :
[project] name = "patrick" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.8" dependencies = [ "requests>=2.32.4", ] [dependency-groups] dev = [ "pytest>=8.3.5", "ruff>=0.15.20", ]
uv run et uv sync installent toujours vos dépendances de production et le groupe dev. Pour obtenir uniquement l'environnement de production, sans pytest ni ruff, il faut explicitement demander à uv de l'exclure :
uv sync --no-dev
Vous pourriez créer un groupe personnalisé avec un autre nom. Par exemple, si vous avez besoin de la dépendance sphinx pour votre documentation, mais que vous voulez créer un groupe dédié à cette dépendance :
uv add --group docs sphinx
uv crée la clé docs dans le fichier pyproject.toml. Contrairement au groupe dev qui est installé automatiquement, un groupe personnalisé doit toujours être demandé explicitement.
Si vous souhaitez retirer une dépendance :
uv remove requests
Une fois qu'une dépendance est verrouillée dans un uv.lock, uv utilisera cette version même si une version plus récente existe. Si une nouvelle version d'une dépendance paraît, vous pouvez la mettre à jour :
uv lock --upgrade-package requests
Si vous migrez un ancien projet qui possède déjà un requirements.txt, uv sait le lire directement :
uv add -r requirements.txt
Gérer les versions de Python
Vous pouvez directement gérer les versions de Python avec uv. Pour savoir quelles versions sont disponibles, vous pouvez les lister :
uv python list
Liste des versions avec uv
Vous remarquerez que les versions de Python installées apparaissent aussi dans cette liste 😎.
Pour installer une version :
uv python install 3.13.13
Vous pouvez créer un projet directement avec une version précise :
uv init --python 3.12 mon-projet
Si vous ne spécifiez pas de version, uv ne prend pas une version au hasard. Il va chercher à « découvrir » les versions selon ses propres règles que vous pouvez retrouver dans la documentation.
Dans un projet existant, vous pouvez même mettre à jour la version de Python utilisée via :
uv python pin 3.13.13
Outils en ligne de commande
Des scripts qui embarquent leur environnement
Imaginez un petit script que vous voulez partager et qui dépend de la bibliothèque requests. Plutôt que d'imposer à votre collègue de créer un environnement et d'installer les dépendances, uv permet de déclarer ces dépendances directement dans le fichier.
Partons d'un script simple :
import requests response = requests.get("https://example.com/") print(response.text)
Vous spécifiez quelle(s) dépendance(s) est/sont nécessaire(s) :
uv add --script main.py requests
Et voici l'état du script après la commande :
# /// script # requires-python = ">=3.13" # dependencies = [ # "requests>=2.34.2", # ] # /// import requests response = requests.get("https://example.com/") print(response.text)
Il ne reste plus qu'à lancer le script :
uv run main.py
uv lit les métadonnées, crée un environnement dans le cache et exécute le tout. Il faut savoir que cet environnement n'est pas supprimé après coup : uv le garde en cache, dans un répertoire global accessible via uv cache dir. Si jamais vous voulez nettoyer le cache, il suffit d'exécuter la commande uv cache clean.
Lancer des outils sans installation globale
La commande uvx exécute un outil sans l'installer globalement sur votre machine. Prenons ruff pour exemple :
uvx ruff check .
C'est le même comportement que celui que l'on a vu précédemment : le premier uvx ruff installe ruff dans un environnement mis en cache, et les appels suivants réutilisent directement cette version en cache, sans tout retélécharger.
Mais si vous voulez l'installer durablement comme outil global :
uv tool install ruff
Vous n'avez plus besoin de passer par uv, vous pouvez lancer directement ruff check ..
En espérant que ce guide vous aura aidé, car il n'est effectivement pas évident de passer d'un outil à un autre, surtout quand ces derniers touchent à vos environnements de développement. Pour ma part, j'avoue être conquis par uv ☺️.
