Guide : Maîtriser le développement Python moderne avec `uv`¶

Introduction : Pourquoi ce guide ?¶

En tant que futur développeur, vous allez rapidement rencontrer deux problèmes majeurs en Python :

Le Chaos des Dépendances : Un projet a besoin d’une vieille version d’une bibliothèque, tandis qu’un autre projet a besoin de la version la plus récente.
“Ça marche sur ma machine, mais pas sur la tienne” : Votre code fonctionne chez vous, mais plante chez votre collègue car il lui manque une version précise d’un outil.

Ce guide vous présente uv, l’outil ultra-rapide qui résout ces problèmes en gérant tout pour vous.

1. Le concept fondamental : L’Environnement Virtuel¶

Avant d’utiliser des outils, il faut comprendre pourquoi nous les utilisons.

Le problème : L’installation globale¶

Par défaut, si vous installez une bibliothèque (ex: pip install django), elle est installée “globalement” sur votre ordinateur.

Le risque : Si vous avez deux projets avec des versions différentes de Django, l’installation du deuxième écrasera celle du premier. Vous cassez votre projet A pour faire fonctionner votre projet B.

La solution : La “Bulle” (L’Environnement Virtuel)¶

Un environnement virtuel est une bulle magique isolée autour de votre projet.

À l’intérieur de la bulle du Projet A, vous installez Django 3.0.
À l’intérieur de la bulle du Projet B, vous installez Django 5.0.
Les deux projets sont totalement indépendants. Ce qui se passe dans l’un n’affecte jamais l’autre.

Le rôle de `uv`¶

Traditionnellement, gérer ces bulles est pénible : il faut les créer, les “activer”, s’en souvenir… uv automatise tout cela. Il crée la bulle, la remplit et s’assure que vous utilisez toujours la bonne, sans que vous ayez à y penser.

Si vous utilisez PyCharm

Si vous utilisez PyCharm, vous pouvez utiliser l’extension uv pour gérer vos environnements virtuels. Cela vous permettra de créer, activer et désactiver vos environnements virtuels directement depuis l’interface de PyCharm. Dans ce cas, vous n’avez pas besoin d’installer uv manuellement. Dans les versions récentes de PyCharm, cette extension est déjà incluse.

2. Installation de `uv`¶

Ouvrez votre terminal et tapez la commande selon votre système :

macOS / Linux :

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

Windows (PowerShell) :

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Une fois installé, redémarrez votre terminal.

3. Workflow de base : Créer un projet de A à Z¶

Voici la méthode standard pour démarrer n’importe quel projet proprement.

Étape 1 : Initialiser le projet¶

Créez un dossier et initialisez l’environnement uv.

mkdir mon_projet
cd mon_projet
uv init

uv crée automatiquement un fichier pyproject.toml (votre configuration) et un fichier hello.py.

Étape 2 : Ajouter des bibliothèques (Dépendances)¶

Supposons que vous vouliez utiliser la bibliothèque requests.

uv add requests

uv installe la bibliothèque dans votre “bulle” isolée et met à jour vos fichiers de configuration.

Étape 3 : Exécuter votre code¶

Vous n’avez pas besoin d’activer manuellement un environnement. uv s’en occupe.

uv run hello.py

4. Les deux fichiers indispensables (Comprendre la théorie)¶

Dans votre dossier, vous verrez deux fichiers cruciaux. Il est vital de comprendre la différence :

pyproject.toml (La liste de courses) : C’est ici que vous listez les bibliothèques dont vous avez besoin (ex: requests >= 2.31). C’est un fichier que vous lisez et modifiez.
uv.lock (La facture détaillée) : C’est ici que uv note les versions exactes (au millième près) de TOUTES les bibliothèques installées. C’est ce fichier qui garantit que votre projet fonctionnera de la même manière sur n’ importe quel ordinateur.

⚠️ Règle d’or : Ne modifiez jamais le fichier uv.lock à la main. Laissez uv le gérer.

5. Gérer les versions de Python¶

Avec uv, vous n’avez plus besoin de télécharger Python manuellement sur un site web. uv gère même l’installation de Python lui-même !

Installer une version spécifique de Python :
```
uv python install 3.12
```
Forcer un projet à utiliser une version précise :
```
uv python pin 3.11
```
Lister les versions de Python installées sur votre machine :
```
uv python list
```

6. Aide-mémoire¶

Action	Commande `uv`	Pourquoi l’utiliser ?
Démarrer un projet	`uv init`	Créer la structure de base.
Ajouter un paquet	`uv add <paquet>`	Installer une bibliothèque dans la “bulle”.
Supprimer un paquet	`uv remove <paquet>`	Retirer une bibliothèque.
Lancer un script	`uv run <script.py>`	Exécuter le code dans la bonne bulle.
Synchroniser	`uv sync`	Installer toutes les versions du fichier `.lock`.
Installer Python	`uv python install 3.x`	Installer une version de Python sans rien faire d’autre.
Outil de développement	`uv add --dev pytest`	Ajouter un outil utile uniquement pour le développement.

Conseils pour réussir vos projets¶

N’installez rien “globalement” : Utilisez toujours uv add dans un projet initialisé avec uv init.
Utilisez toujours uv run : Cela garantit que vous travaillez dans l’environnement du projet et non sur le Python de votre ordinateur.
Partagez vos fichiers de configuration : Si vous travaillez en groupe, envoyez toujours votre pyproject.toml et votre uv.lock sur GitHub. Vos camarades n’auront qu’à taper uv sync pour avoir exactement le même environnement que vous.

Guide : Maîtriser le développement Python moderne avec uv¶