Python uv — Bonnes pratiques : checklist stabilité et collaboration

En pratique, les environnements cassent souvent non pas parce que « uv n'est pas assez puissant », mais à cause du processus et des habitudes. Cette checklist peut servir de guide au quotidien — chaque piège évité, c'est une fois de plus où vous partez à l'heure.

Pratiques recommandées

1) Toujours versionner uv.lock

Le lockfile est la base de la reproductibilité. Ne pas le versionner, c'est laisser chaque personne, chaque machine, chaque run CI installer un arbre différent — reproduire un bug devient l'enfer. Un projet sans lockfile, c'est comme des chaussures jamais essayées : vous découvrez qu'elles font mal en plein combat.

2) Ne jamais versionner .venv

L'environnement virtuel est un artefact local — il doit être dans .gitignore. uv ajoute automatiquement .venv au fichier d'ignore du projet ; vérifiez juste qu'il y est.

3) Contraintez les dépendances quand c'est possible

Dans pyproject.toml, évitez un simple requests — préférez requests>=2.31,<3 ou plus précis. uv add ajoute des contraintes raisonnables par défaut ; en édition manuelle, ne laissez pas la plage trop large.

4) Utilisez uv sync ou uv pip sync en CI

# Exemple GitHub Actions
- run: uv sync
- run: uv run pytest

Sync d'abord, puis exécution — l'environnement reste aligné sur le lockfile. Ne lancez pas uv add en CI ; ça modifie le lockfile et peut créer des diffs inattendus.

5) Mettez les outils de dev en optional / dev

uv add --dev pytest ruff mypy

Tests, lint et typage n'impactent pas les dépendances de prod et ne sont pas emballés dans la wheel. Les images de prod n'ont besoin que de uv sync --no-dev.

Pièges courants

Piège 1 : Mélanger pip et uv add

N'utilisez pas à la fois pip install et uv add dans le même venv — le lockfile se désynchronise. Choisissez une voie et tenez-vous-y.

Piège 2 : Utiliser uvx pour les outils du projet

Outils du projet avec version fixée (pytest, mypy) → utilisez uv add --dev + uv run. Usage ponctuel temporaire → utilisez uvx.

Piège 3 : Éditer pyproject.toml à la main sans le relire

Pour les changements de dépendances, préférez uv add / uv remove — évite les soucis de format et les oublis de mise à jour du lockfile.

Piège 4 : Ne pas installer uv en CI

Beaucoup de CI supportent uv — installation rapide, exécution encore plus rapide. Utilisez l'installateur officiel ou pip install uv ; ne restez pas indéfiniment sur pip pour la résolution.

Piège 5 : Pas de requires-python dans le projet

Dans pyproject.toml, indiquez requires-python = ">=3.12" etc., pour que les outils et collaborateurs connaissent la version minimale. Évite le « ça tourne en 3.12 chez moi, ça plante en 3.8 chez toi ».

Suivre cette checklist ne garantit pas zéro panne, mais vous éviterez bien des détours inutiles. En cas de doute, consultez la doc officielle — la plupart des pièges ont déjà été rencontrés. Bon dev — que vos dépendances s'installent proprement, les tests restent verts et la CI arrête de vous faire attendre ! 🦦 (Et après avoir utilisé uv, vous réaliserez : le temps que vous passiez à regarder le spinner de pip suffit maintenant à caresser le chat trois fois.)