uv

Mis à jour le 2026-08-07Confiance : high

uvpythonpackagingvenvpipastralenvironnement

Gestionnaire de projets Python en Rust. Remplace pyenv + venv + pip + pip-tools d'un seul coup, et télécharge ses propres interpréteurs.

Démarrer un projet

uv init --python 3.12 mon-projet
cd mon-projet
uv add httpx pydantic pytest
uv run python -V

Using CPython 3.12.11
Creating virtual environment at: .venv
Python 3.12.11

Toujours passer --python. Sans lui, uv prend sa version par défaut — souvent une 3.13 ou 3.14 — et écrit requires-python = ">=3.13" dans le pyproject.toml.

uv init crée pyproject.toml, .python-version, main.py, README.md, .gitignore et un dépôt git. Le .venv/ n'apparaît qu'au premier add ou run.

Variante	Résultat
`uv init`	projet application, fichiers à plat
`uv init --package`	`src/<nom>/__init__.py` + `[build-system]`
`uv init --lib`	idem plus `py.typed`

Le quotidien

uv add httpx                  # ajoute et installe
uv add --dev pytest ruff      # dépendance de dev
uv remove httpx
uv sync                       # aligne .venv sur uv.lock
uv lock                       # regénère le lock sans installer
uv tree                       # arbre des dépendances
uv run <commande>             # exécute dans le venv, sans activation

uv add et uv run synchronisent implicitement. uv sync sert surtout après un clone, ou quand le .venv est cassé.

uv sync désinstalle ce qui n'est pas dans le lock, contrairement à pip install -r.

uv sync

Resolved 100 packages in 4ms
Uninstalled 3 packages in 8ms
 - markdown-it-py==4.2.0
 - mdurl==0.1.2
 - rich==15.0.0

Reprendre un repo existant

git clone <url> && cd <repo> && ls

Ce qu'on trouve	Ce qu'on lance
`uv.lock`	`uv sync`
`pyproject.toml` seul	`uv sync` (le lock est généré)
`requirements.txt`	`uv venv --python 3.12` puis `uv pip install -r requirements.txt`
`poetry.lock`	`poetry install`, ou `uv pip install -e .`
rien	`uv init --python 3.12`

uv venv + uv pip ne modifient aucun fichier du repo — c'est la voie propre pour accélérer l'installation chez un client sans imposer son outillage.

Le piège `.python-version`

uv et pyenv lisent ce fichier. Si uv y écrit 3.13 et que pyenv n'a pas de 3.13, pyenv affiche une erreur à chaque commande dans ce dossier. C'est du bruit, uv continue de fonctionner, mais c'est pénible.

# corriger requires-python dans pyproject.toml D'ABORD
uv python pin 3.12

Updated `.python-version` from `3.13` -> `3.12`

Dans l'autre ordre, uv refuse : The requested Python version 3.12 is incompatible with the project requires-python value of >=3.13.

Outils globaux

uv tool install ruff          # installé isolément, disponible partout
uv tool list
uvx ruff check .              # exécute sans installer

Diagnostic

uv run python -c "import sys; print(sys.executable)"

/Users/edouard/code/mon-projet/.venv/bin/python3

Le chemin doit contenir /.venv/ et être dans le projet. S'il pointe vers .pyenv/shims, /opt/homebrew ou /usr/bin, on n'est pas où on croit.

uv python list        # interpréteurs connus
uv cache clean        # vider le cache

Pour un live coding sous pression, activer une fois et oublier le préfixe :

source .venv/bin/activate

uv