Gestionnaire de paquets UV

Guide complet d'utilisation d'uv, un installateur et résolveur de paquets Python extrêmement rapide écrit en Rust, pour la gestion moderne de projets Python et les workflows de dépendances.

Quand utiliser cette compétence

Configurer rapidement de nouveaux projets Python
Gérer les dépendances Python plus rapidement que pip
Créer et gérer des environnements virtuels
Installer des interpréteurs Python
Résoudre efficacement les conflits de dépendances
Migrer depuis pip/pip-tools/poetry
Accélérer les pipelines CI/CD
Gérer des projets monorepo Python
Travailler avec des lockfiles pour des builds reproductibles
Optimiser les builds Docker avec les dépendances Python

Concepts fondamentaux

1. Qu'est-ce qu'uv ?

Installateur ultra-rapide : 10 à 100 fois plus rapide que pip
Écrit en Rust : Tire parti des performances de Rust
Remplacement drop-in de pip : Compatible avec les workflows pip
Gestionnaire d'environnement virtuel : Crée et gère les venvs
Installateur Python : Télécharge et gère les versions Python
Résolveur : Résolution avancée des dépendances
Support des lockfiles : Installations reproductibles

2. Fonctionnalités clés

Vitesses d'installation extrêmement rapides
Cache global efficace en termes d'espace disque
Compatible avec pip, pip-tools, poetry
Résolution complète des dépendances
Support multiplateforme (Linux, macOS, Windows)
Pas besoin de Python pour l'installation
Support intégré des environnements virtuels

3. UV par rapport aux outils traditionnels

vs pip : 10 à 100 fois plus rapide, meilleur résolveur
vs pip-tools : Plus rapide, plus simple, meilleure UX
vs poetry : Plus rapide, moins dogmatique, plus léger
vs conda : Plus rapide, orienté Python

Installation

Installation rapide

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Avec pip (si vous avez déjà Python)
pip install uv

# Avec Homebrew (macOS)
brew install uv

# Avec cargo (si vous avez Rust)
cargo install --git https://github.com/astral-sh/uv uv

Vérifier l'installation

uv --version
# uv 0.x.x

Démarrage rapide

Créer un nouveau projet

# Créer un nouveau projet avec environnement virtuel
uv init my-project
cd my-project

# Ou créer dans le répertoire courant
uv init .

# L'initialisation crée :
# - .python-version (version Python)
# - pyproject.toml (configuration du projet)
# - README.md
# - .gitignore

Installer les dépendances

# Installer les paquets (crée un venv si nécessaire)
uv add requests pandas

# Installer les dépendances de développement
uv add --dev pytest black ruff

# Installer à partir de requirements.txt
uv pip install -r requirements.txt

# Installer à partir de pyproject.toml
uv sync

Gestion des environnements virtuels

Pattern 1 : Créer des environnements virtuels

# Créer un environnement virtuel avec uv
uv venv

# Créer avec une version Python spécifique
uv venv --python 3.12

# Créer avec un nom personnalisé
uv venv my-env

# Créer avec les site-packages système
uv venv --system-site-packages

# Spécifier l'emplacement
uv venv /path/to/venv

Pattern 2 : Activer les environnements virtuels

# Linux/macOS
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Ou utiliser uv run (pas d'activation nécessaire)
uv run python script.py
uv run pytest

Pattern 3 : Utiliser uv run

# Exécuter un script Python (active automatiquement le venv)
uv run python app.py

# Exécuter un outil CLI installé
uv run black .
uv run pytest

# Exécuter avec une version Python spécifique
uv run --python 3.11 python script.py

# Passer des arguments
uv run python script.py --arg value

Gestion des paquets

Pattern 4 : Ajouter des dépendances

# Ajouter un paquet (l'ajoute à pyproject.toml)
uv add requests

# Ajouter avec une contrainte de version
uv add "django>=4.0,<5.0"

# Ajouter plusieurs paquets
uv add numpy pandas matplotlib

# Ajouter une dépendance de développement
uv add --dev pytest pytest-cov

# Ajouter un groupe de dépendances optionnelles
uv add --optional docs sphinx

# Ajouter depuis git
uv add git+https://github.com/user/repo.git

# Ajouter depuis git avec une ref spécifique
uv add git+https://github.com/user/repo.git@v1.0.0

# Ajouter depuis un chemin local
uv add ./local-package

# Ajouter un paquet local modifiable
uv add -e ./local-package

Pattern 5 : Supprimer des dépendances

# Supprimer un paquet
uv remove requests

# Supprimer une dépendance de développement
uv remove --dev pytest

# Supprimer plusieurs paquets
uv remove numpy pandas matplotlib

Pattern 6 : Mettre à jour les dépendances

# Mettre à jour un paquet spécifique
uv add --upgrade requests

# Mettre à jour tous les paquets
uv sync --upgrade

# Mettre à jour un paquet vers la dernière version
uv add --upgrade requests

# Afficher ce qui serait mis à jour
uv tree --outdated

Pattern 7 : Verrouiller les dépendances

# Générer le fichier uv.lock
uv lock

# Mettre à jour le fichier lock
uv lock --upgrade

# Verrouiller sans installer
uv lock --no-install

# Verrouiller un paquet spécifique
uv lock --upgrade-package requests

Gestion des versions Python

Pattern 8 : Installer les versions Python

# Installer une version Python
uv python install 3.12

# Installer plusieurs versions
uv python install 3.11 3.12 3.13

# Installer la dernière version
uv python install

# Lister les versions installées
uv python list

# Trouver les versions disponibles
uv python list --all-versions

Pattern 9 : Définir la version Python

# Définir la version Python pour le projet
uv python pin 3.12

# Cela crée/met à jour le fichier .python-version

# Utiliser une version Python spécifique pour une commande
uv --python 3.11 run python script.py

# Créer un venv avec une version spécifique
uv venv --python 3.12

Configuration du projet

Pattern 10 : pyproject.toml avec uv

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    # Additional dev dependencies managed by uv
]

[tool.uv.sources]
# Custom package sources
my-package = { git = "https://github.com/user/repo.git" }

Pattern 11 : Utiliser uv avec des projets existants

# Migrer depuis requirements.txt
uv add -r requirements.txt

# Migrer depuis poetry
# Vous avez déjà pyproject.toml, utilisez simplement :
uv sync

# Exporter vers requirements.txt
uv pip freeze > requirements.txt

# Exporter avec hashes
uv pip freeze --require-hashes > requirements.txt

Pour les workflows avancés incluant l'intégration Docker, la gestion des lockfiles, l'optimisation des performances, la comparaison des outils, les workflows courants, l'intégration d'outils, le dépannage, les bonnes pratiques, les guides de migration et la référence des commandes, voir references/advanced-patterns.md

uv-package-manager