Python uv — Concepts fondamentaux : pyproject.toml, lockfile et environnements virtuels

Avant de taper des commandes au hasard, intégrez ces quatre concepts : vous y verrez plus clair sur « où vont les dépendances, à quoi sert le lockfile, quand le venv est créé ». Comme lire les descriptions des compétences avant de jouer — sinon vous mourrez sans comprendre pourquoi.

Concept 1 : pyproject.toml est la carte d'identité du projet

Les métadonnées du projet et les dépendances vivent ici — c'est le format standard PEP 518.

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31",
]

Édition manuelle : modifiez pyproject.toml directement
Piloté par commandes : uv add requests et uv remove requests le mettent à jour automatiquement

Ne mélangez pas les deux — soit vous éditez à la main, soit vous utilisez les commandes. Les deux en même temps créent des conflits.

Concept 2 : uv.lock est un instantané des dépendances

pyproject.toml dit « ce que je veux » (ex. requests>=2.31). uv.lock enregistre « ce qui a réellement été installé » — jusqu'à chaque dépendance transitive.

Pourquoi un lockfile ? Garantir que tout le monde — équipe, CI, prod — installe exactement le même arbre de dépendances. Fini le « ça marche chez moi, ça casse chez toi ».
Faut-il le versionner ? Oui. uv.lock doit être dans le contrôle de version pour que l'équipe et la CI utilisent le même arbre.

# Mettre à jour le lockfile (ex. mettre à niveau un paquet)
uv lock --upgrade-package requests

Concept 3 : .venv est le bac à sable du projet

uv crée .venv à la racine du projet — tous les paquets de uv add vont dedans, isolés du Python système.

Faut-il l'activer à la main ? Non. uv run utilise automatiquement cet environnement.
Faut-il le versionner ? Non. .venv doit être dans .gitignore.

# Synchroniser manuellement l'environnement (ex. après un clone)
uv sync
source .venv/bin/activate  # après ça vous pouvez utiliser python, pytest, etc. directement

Concept 4 : uv run est le point d'entrée sans effort

uv run va :

Vérifier que le lockfile est cohérent avec pyproject.toml
S'assurer que .venv est synchronisé avec le lockfile
Exécuter la commande demandée dans le bon environnement

uv run python main.py
uv run pytest
uv run flask run -p 3000

Pas besoin de penser à activer, pas de risque de mauvais environnement — confiez tout à uv. Comme un chat qui trouve la litière sans y penser. Une fois que vous avez goûté à ce « lance et ça tourne », on ne revient pas en arrière.

Suite

Une fois les concepts intégrés, passez aux opérations à haute fréquence : gestion des dépendances, uvx, exécution de scripts. 👉 Modèles courants