Tutoriel de prise en main d'uv -- Outil de gestion des paquets et environnements Python

Dans le développement Python, la gestion des paquets et l'isolation des environnements sont des problèmes que chaque développeur rencontre. Qu'il s'agisse de la lenteur de pip, de la lourdeur de virtualenv ou du gonflement de conda,uvtout cela fait que les développeurs attendent avec impatience une solution plus efficace.

Qu'est-ce que uv ?

uv est un gestionnaire de paquets et d'environnements Python développé par Astral en Rust. Son objectif principal est d'offrir des performances 10 à 100 fois plus rapides que les outils existants, tout en conservant une expérience utilisateur simple et intuitive.

uv peut remplacer des outils tels que pip, virtualenv, pip-tools et pyenv, offrant des services tout-en-un pour la gestion des dépendances, la création d'environnements virtuels et la gestion des versions de Python.

Avantages d'uv

  • Extrêmement rapide: parce qu'il est écrit en Rust, les performances d'uv dépassent largement celles de pip et des autres outils de gestion de paquets, et la vitesse d'installation des dépendances peut être améliorée de 10 à 100 fois.
  • Fonctionnalités intégrées: il intègre la résolution des dépendances, l'installation des paquets, la gestion des environnements et la gestion des versions de Python en un seul outil, sans avoir besoin d'installer et d'apprendre plusieurs outils.
  • Builds déterministes: uv génère unuv.lockfichier, garantissant que des versions de dépendances exactement identiques peuvent être installées dans n'importe quel environnement, évitant le problème de « ça marche sur ma machine ».
  • Compatibilité avec les outils existants: uv peut gérerrequirements.txtetpyproject.toml, et peut remplacer pip de manière transparente dans les workflows existants.

Installation d'uv

Installation sur macOS

Il est recommandé d'installer via Homebrew :

brew install uv

Ou utilisez le script d'installation officiel :

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

Installation sous Linux

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

Installation sous Windows

Utilisation de Winget :

winget install uv

Ou utilisez le script d'installation officiel (PowerShell) :

irm https://astral.sh/uv/install.ps1 | iex

Après l'installation, vérifiez si elle a réussi :

uv --version

La sortie est similaire à ce qui suit, ce qui indique que l'installation a réussi :

uv 0.8.14 (Homebrew 2025-08-28)

1. Gestion des versions de Python

uv dispose d'une fonctionnalité intégrée de gestion des versions de Python, il n'est donc pas nécessaire d'installer des outils supplémentaires tels que pyenv.

Afficher les versions de Python disponibles :

uv python list

Le résultat de sortie est similaire à ce qui suit :

cpython-3.14.0rc2-macos-aarch64-none                 <download available>
cpython-3.13.7-macos-aarch64-none                    <download available>
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
pypy-3.11.13-macos-aarch64-none                      <download available>

Installer une version spécifique de Python :

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

Définir la version globale par défaut de Python :

uv python default 3.12

Épingler la version de Python pour le projet actuel (cela créera un.python-versionfichier) :

uv python pin 3.12

Après avoir exécuté cette commande, un fichier .python-version sera généré dans le répertoire du projet actuel. Lorsqu'il est ouvert, il affiche le contenu du numéro de version :

3.12

2. Gestion des environnements virtuels

Créer un environnement virtuel :

# 在当前目录创建名为 .venv 的虚拟环境（使用系统默认 Python）
uv venv

# 使用指定 Python 版本创建虚拟环境
uv venv --python 3.12

Activez l'environnement virtuel :

# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.venv\Scripts\activate

Quittez l'environnement virtuel :

deactivate

Dans le développement quotidien, vous pouvez utiliseruv runpour exécuter directement des scripts sans activer manuellement l'environnement virtuel.

3. Gestion des paquets (mode de compatibilité pip)

uv fournit une interface en ligne de commande entièrement compatible avec pip, qui peut remplacer directement les commandes pip dans les flux de travail existants :

Installez des paquets :

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

# 从 requirements.txt 批量安装
uv pip install -r requirements.txt

Mettez à niveau des paquets :

uv pip install --upgrade requests

Désinstallez des paquets :

uv pip uninstall requests

Afficher les paquets installés :

uv pip list

Exportez les dépendances de l'environnement actuel vers requirements.txt :

uv pip freeze > requirements.txt

4. Gestion de projet (approche recommandée)

uv prend en charge unpyproject.toml, plus recommandée que le mode pip, particulièrement adaptée à la collaboration en équipe et au déploiement multi-environnement.

Initialisation d'un projet

uv init my_project
cd my_project

Cela créera la structure de projet de base suivante :

my_project/
├── pyproject.toml    # 项目配置和依赖声明
├── .python-version   # 固定 Python 版本
├── README.md
└── main.py

Ajout et suppression de dépendances

En mode projet, il est recommandé d'utiliseruv addetuv removepour gérer les dépendances ; elles se mettront à jour automatiquementpyproject.tomletuv.lock：

# 添加生产依赖
uv add requests

# 添加指定版本的依赖
uv add "requests>=2.31.0"

# 添加开发依赖（只在开发环境使用，如测试框架）
uv add --dev pytest ruff

# 移除依赖
uv remove requests

Installation de toutes les dépendances du projet (uv sync)

Après avoir cloné le projet ou mis à jourpyproject.toml, exécutez la commande suivante pour installer toutes les dépendances en un clic :

uv sync

explication de uv sync :Similaire àpip install -r requirements.txt, il va, sur la base depyproject.tomletuv.lockinstaller toutes les dépendances, en s'assurant que l'environnement est exactement le même que celui des autres développeurs. Si l'installation est lente, vous pouvez, danspyproject.tomldéfinir une source miroir domestique :

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Génération/Mise à jour des fichiers de verrouillage

uv lock

Cette commande va analyserpyproject.tomlet générer (ou mettre à jour) leuv.lockfichier.uv.lockIl doit être commité dans le dépôt de gestion de versions afin de garantir que tous les membres de l'équipe utilisent exactement les mêmes versions de dépendances.

5. Exécution de scripts (uv run)

uv runest une commande très pratique dans uv, vous permettant de, sans activer manuellement l'environnement virtuel,exécuter directement des scripts ou des commandes. uv trouvera et utilisera automatiquement l'environnement correct :

# 直接运行 Python 脚本
uv run main.py

# 运行项目中的测试
uv run pytest

# 运行任意命令（在虚拟环境的上下文中执行）
uv run python -c "import requests; print(requests.__version__)"

Utilisationuv run, par rapport à l'activation manuelle de l'environnement, présente ces avantages : vous n'utiliserez pas accidentellement la mauvaise version de Python, et vous n'oublierez pas d'activer l'environnement, ce qui ferait que les paquets ne seraient pas trouvés. Il est particulièrement adapté à une utilisation dans CI/CD et pour l'automatisation de scripts.

Migration vers uv

Si vous utilisez d'autres outils, vous pouvez migrer vers uv des manières suivantes :

Migration depuis pip + virtualenv :

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装原有依赖
uv pip install -r requirements.txt

Migration depuis pip-tools :

# 编译依赖（替代 pip-compile）
uv pip compile requirements.in -o requirements.txt

# 同步环境（替代 pip-sync）
uv pip sync requirements.txt

Migration depuis poetry ou pdm :

# 直接使用现有的 pyproject.toml
uv sync
Autres extensions