uv : environnements de projet et dépendances Python
Pour un dépôt ordinaire dont les dépendances sont disponibles sur les index de paquets Python et disposent de wheels adaptées, le choix par défaut est clair :
uv + pyproject.toml + uv.lock + .venv local au dépôt
Cela ne rend pas Conda obsolète. uv gère principalement les projets Python, les versions de Python, la résolution des dépendances et l'exécution des commandes. Conda peut également gérer les bibliothèques natives, les exécutables non-Python et les environnements multilangages. Donnez à chaque environnement un propriétaire explicite ; ne laissez pas pip, uv et Conda le modifier tour à tour.
Choisir par frontière
Une longue sortie de conda list n'est pas une liste de dépendances directes. Elle contient des paquets transitifs, des runtimes natifs et l'infrastructure de Conda. Reconstituez l'intention à partir de pyproject.toml, des fichiers de requirements, des imports dans le code source, des points d'entrée, des tests et des commandes de déploiement.
Modèle de projet
pyproject.toml plage de versions Python visée et dépendances directes
uv.lock graphe exact des dépendances résolu par uv
.python-version choix facultatif de Python pour le projet
.venv/ installation locale ; ignorée par Git
Commitez uv.lock ; ne l'éditez pas manuellement. Un verrou capture une résolution, et non la confiance, la sécurité, les licences ou l'aptitude au déploiement.
Démarrer un projet
uv python install 3.12
uv init --python 3.12 example-app
cd example-app
uv python pin 3.12
uv add requests
uv add --dev pytest
uv sync
uv run python --version
# Après avoir créé les tests du projet, exécutez :
# uv run python -m pytest
Pour une collection de scripts internes qui n'est pas installée comme un paquet :
[project]
name = "example-tool"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []
[tool.uv]
package = false
package = false modifie le comportement d'installation ; cela n'élimine pas le besoin de tests, de versions et de déclarations de dépendances.
Adopter un dépôt existant
- Lire les métadonnées de projet existantes, les requirements, les points d'entrée, la CI et les chemins de lancement en production.
- Déclarer uniquement les dépendances directement requises par le code et les chemins d'exécution ; ne pas copier en bloc un environnement installé.
- Si
pyproject.tomlexiste, commencer paruv locketuv sync; migrer les requirements en suivant le guide officiel. - Conserver l'ancien environnement et construire un
.venvlocal au dépôt en tant qu'environnement miroir. - Exécuter la compilation, les tests unitaires/d'intégration et des charges de travail représentatives en lecture seule.
- Pour les charges de calcul numérique ou de données, comparer les résultats, les backends, le threading et les performances — pas seulement les imports.
- Basculer la CI, les ordonnanceurs, les services ou les éditeurs en dernier, avec une cible de retour arrière explicite.
Ne combinez pas une migration de gestionnaire d'environnement avec une mise à niveau de Python, une actualisation large des dépendances ou une refactorisation d'application ; cela détruit le diagnostic de causalité.
Commandes du quotidien
# Restore and execute
uv sync
uv run python --version
uv run python script.py
uv run python -m unittest discover -s tests
uv pip check
# Change declarations deliberately
uv add pandas
uv add --dev pytest
uv remove pandas
uv tree
# Require an unchanged lock
uv lock --check
uv sync --locked
uv run --locked python -m pytest
# Run a tool without adding it to project dependencies
uvx ruff check .
Par défaut, uv sync met à jour le verrou lorsque les métadonnées du projet l'exigent ; consultez la documentation officielle sur le verrouillage et la synchronisation pour ce comportement et la distinction entre --locked et --frozen. La CI et les procédures de publication peuvent utiliser --locked pour que des métadonnées obsolètes provoquent un échec plutôt que de produire silencieusement une autre résolution. --frozen utilise le verrou existant sans vérifier sa cohérence ; utilisez-le uniquement lorsque cette distinction est intentionnelle.
Privilégiez uv add/remove plutôt qu'une installation manuelle dans .venv. L'environnement est jetable ; pyproject.toml et uv.lock détiennent l'état du projet.
Coexister avec Conda
La coexistence doit s'effectuer au niveau du dépôt, et non par le biais de deux résolveurs gérant un même environnement :
- un projet peut utiliser uv tandis qu'un autre conserve Conda ;
- un projet peut temporairement conserver une référence Conda à côté d'un environnement miroir uv indépendant ;
- si Conda gère un environnement d'exécution natif, documenter la responsabilité et le chemin complet de la commande ;
- un
uv syncréussi ne donne pas l'autorisation de supprimer l'environnement de référence ou de modifier la production.
Prédéfinissez les critères de bascule : les tests passent, les sorties représentatives concordent, les vérifications de dépendances sont propres, l'installation sur la plateforme cible réussit, le comportement à l'exécution est vérifié et le retour arrière est répété.
Pannes fréquentes
Frontière de confidentialité pour les notes publiques
Les exemples publics utilisent example-app, /path/to/repository et des services fictifs. Les noms de dépôts, domaines internes, noms d'utilisateurs, répertoires absolus, unités de service, statuts de migration, nombres de tests et dépendances non publiées appartiennent aux dossiers opérationnels privés. Un guide d'outils public doit préserver des décisions et des méthodes de vérification réutilisables, et non publier l'inventaire des actifs d'un environnement de travail.