uv pour débuter en Python : installer des paquets simplement

Installer une bibliothèque est une étape normale dès que l’on dépasse les premiers scripts Python. Vous voulez envoyer une requête web, lire un fichier Excel, créer un graphique ou manipuler des données ? Python possède une immense collection de bibliothèques prêtes à l’emploi.

Le problème est que les débutants rencontrent vite des commandes comme pip, venv, « environnement virtuel » ou « dépendances ». Ces mots donnent l’impression qu’il faut devenir administrateur système avant de pouvoir utiliser une bibliothèque. Ce n’est pas le cas.

uv, prononcé « you-vee », est un outil créé par Astral. Il aide à créer des projets Python, à installer des bibliothèques et à isoler leurs dépendances. Son objectif est de réunir des tâches souvent séparées entre pip, venv et d’autres outils, avec des commandes courtes et cohérentes.

Dans ce guide, vous allez comprendre ce que uv apporte, créer un premier projet propre et installer la bibliothèque requests. Vous n’avez pas besoin de maîtriser tous les détails techniques pour commencer.

Pourquoi installer une bibliothèque Python peut sembler compliqué

Python est livré avec une bibliothèque standard : un ensemble de modules déjà disponibles après l’installation. Par exemple, math permet de faire des calculs mathématiques et random de générer de l’aléatoire. Vous pouvez les importer sans rien installer :

import math
print(math.sqrt(25))

Vous pouvez découvrir ce principe dans notre guide sur les modules Python et l’instruction import. Mais beaucoup d’outils utiles ne font pas partie de Python par défaut. C’est notamment le cas de requests, utilisée pour communiquer avec des sites et des API HTTP, ou de pandas, très employée pour analyser des tableaux de données.

Traditionnellement, on installe une bibliothèque avec pip :

pip install requests

La commande fonctionne souvent très bien. Pourtant, elle soulève rapidement quelques questions :

Dans quelle installation de Python le paquet est-il ajouté ?
Est-ce que cette bibliothèque sera disponible dans tous vos projets ?
Comment éviter qu’un projet utilisant une ancienne version entre en conflit avec un autre ?
Comment transmettre à une autre personne la liste exacte des bibliothèques nécessaires ?

Ces questions deviennent importantes parce qu’un projet Python dépend généralement de plusieurs paquets, et que ces paquets peuvent eux-mêmes dépendre d’autres paquets. On appelle cela des dépendances. Par exemple, votre projet dépend de requests parce que vous l’avez choisi ; requests dépend aussi d’autres composants pour fonctionner.

Il n’est pas nécessaire de connaître chaque dépendance pour coder. En revanche, il est utile que votre outil les installe et les enregistre correctement. C’est précisément l’un des rôles de uv.

Découvrir uv, un outil moderne pour les projets Python

uv est un outil en ligne de commande écrit en Rust et distribué par Astral. Il peut installer des versions de Python, créer et gérer des environnements virtuels, installer des paquets et gérer les dépendances d’un projet.

Pour un débutant, l’intérêt principal est simple : au lieu d’enchaîner plusieurs outils et plusieurs fichiers à créer à la main, vous pouvez démarrer avec une suite de commandes homogène.

Avec uv, vous pouvez notamment :

créer le dossier et les fichiers de départ d’un projet ;
créer automatiquement un environnement isolé pour ce projet ;
ajouter une bibliothèque avec une commande explicite ;
conserver la liste des dépendances dans le projet ;
exécuter votre programme dans le bon environnement.

Le terme isolé mérite une explication. Imaginez deux recettes : l’une a besoin de chocolat noir, l’autre de chocolat au lait. Si vous mélangez tous les ingrédients dans le même saladier, vous risquez de ne plus savoir ce qui appartient à quelle recette. Un environnement isolé joue le rôle d’un saladier par projet : les bibliothèques installées pour votre programme ne viennent pas modifier les autres projets.

uv ne change pas le langage Python. Vous continuez à écrire des variables, des fonctions, des conditions et des fichiers Python habituels. Si vous découvrez ces bases, consultez par exemple le guide sur les fonctions en Python. uv s’occupe surtout de l’organisation autour de votre code.

Installer uv sur votre ordinateur

Avant d’utiliser uv, vérifiez que Python est présent sur votre machine. Sur un terminal, cette commande affiche normalement une version de Python :

python --version

Selon votre système, il peut être nécessaire d’utiliser :

python3 --version

Si aucune version ne s’affiche, commencez par suivre notre guide pour installer Python et configurer VS Code. uv peut également gérer des installations de Python, mais il est plus rassurant, au début, de vérifier que votre interpréteur Python fonctionne déjà.

Les instructions d’installation à jour sont disponibles dans la documentation officielle de uv. Astral propose notamment une commande d’installation pour macOS et Linux, ainsi qu’une commande PowerShell pour Windows. Suivez de préférence la procédure correspondant à votre système, car les commandes peuvent évoluer.

Après l’installation, ouvrez un nouveau terminal, puis vérifiez que uv est reconnu :

uv --version

Si le terminal affiche une version, uv est prêt. Si la commande est introuvable, fermez et rouvrez le terminal. Il est aussi possible que le chemin d’installation n’ait pas encore été ajouté aux variables d’environnement de votre système : la documentation officielle indique alors les étapes adaptées à chaque plateforme.

Dans VS Code, vous pouvez ouvrir le terminal intégré avec le menu Terminal, puis Nouveau terminal. Vous pouvez tout faire depuis cet espace : créer le projet, installer requests et lancer votre fichier.

Créer votre premier projet avec uv

Choisissez un emplacement simple pour vos exercices, par exemple un dossier nommé projets-python. Dans le terminal, placez-vous dans ce dossier. La manière de se déplacer dépend du système, mais la commande cd signifie « changer de dossier ».

Créez ensuite un nouveau projet nommé bonjour-requests :

uv init bonjour-requests

uv crée un dossier portant ce nom, ainsi que plusieurs fichiers utiles. Entrez dans ce nouveau dossier :

cd bonjour-requests

Vous trouverez généralement un fichier pyproject.toml. Ne vous inquiétez pas de son apparence : c’est un fichier de configuration courant dans les projets Python modernes. Il contient notamment le nom du projet et, plus tard, les bibliothèques dont il dépend.

Vous trouverez aussi un fichier Python de départ, souvent nommé main.py. Ouvrez le dossier du projet dans VS Code. Si la commande code est disponible sur votre machine, vous pouvez le faire depuis le terminal :

code .

Le point signifie ici « le dossier actuel ». Vous pouvez aussi ouvrir VS Code normalement, puis choisir Fichier et Ouvrir un dossier.

À ce stade, votre projet ne fait pas encore grand-chose. Vous pouvez remplacer le contenu de main.py par :

print("Mon projet uv fonctionne !")

Pour l’exécuter, utilisez :

uv run main.py

La commande uv run lance votre programme dans l’environnement du projet. Lors de la première exécution, uv peut créer un dossier nommé .venv. Ce dossier contient l’environnement virtuel local du projet. Vous n’avez pas besoin de l’ouvrir ni de modifier son contenu.

Retenez surtout cette habitude : dans un projet uv, lancez votre fichier avec uv run. Cela réduit le risque d’exécuter le script avec le mauvais Python ou avec des bibliothèques installées ailleurs.

Ajouter requests pas à pas avec uv add

Passons à une bibliothèque concrète. requests simplifie l’envoi de requêtes HTTP. Elle peut par exemple demander une page web ou interroger une API. Son nom sur l’index de paquets Python est requests sur PyPI.

Dans le terminal, toujours placé dans le dossier bonjour-requests, ajoutez-la ainsi :

uv add requests

Cette commande fait plusieurs choses importantes :

elle télécharge requests et les éléments nécessaires à son fonctionnement ;
elle l’installe dans l’environnement du projet ;
elle ajoute requests à la configuration du projet ;
elle met à jour le fichier de verrouillage des dépendances, nommé uv.lock.

Le fichier uv.lock est utile lorsque vous revenez sur un projet plus tard ou lorsque vous le partagez. Il conserve une résolution précise des dépendances utilisées par uv. Vous n’avez pas à le rédiger manuellement : laissez l’outil le gérer.

Modifiez maintenant main.py pour importer requests :

import requests

reponse = requests.get("https://httpbin.org/get", timeout=10)
print(reponse.status_code)

Puis lancez le programme :

uv run main.py

Si tout se passe bien, le programme affiche 200. En HTTP, ce code signifie que le serveur a traité la requête avec succès. Le site httpbin.org est un service destiné à tester des requêtes HTTP ; son point d’entrée /get répond aux requêtes GET.

Cet exemple montre une idée essentielle : vous n’avez pas seulement installé requests sur votre ordinateur. Vous l’avez ajoutée au projet. Si vous créez un autre dossier avec uv init, requests n’y sera pas présente tant que vous ne l’y ajoutez pas. C’est volontaire et c’est une bonne pratique.

Si vous obtenez une erreur liée au réseau, vérifiez votre connexion Internet ou réessayez plus tard. Si Python indique qu’il ne trouve pas requests, assurez-vous d’être dans le bon dossier et lancez bien uv run main.py, plutôt que python main.py.

Comprendre les fichiers créés sans se noyer dans les détails

Un projet uv contient plusieurs éléments. Vous n’avez pas besoin de tout apprendre par cœur, mais savoir à quoi ils servent évite de les supprimer par erreur.

main.py : votre programme Python ;
pyproject.toml : les informations générales du projet et ses dépendances directes ;
uv.lock : les versions résolues par uv pour installer un environnement reproductible ;
.venv : l’environnement virtuel local, où les bibliothèques sont effectivement installées.

Vous pouvez ouvrir pyproject.toml dans VS Code. Après l’ajout de requests, vous y verrez cette dépendance déclarée. C’est utile : une personne qui récupère votre projet sait qu’il a besoin de requests.

En revanche, évitez de modifier uv.lock à la main au début. Ce fichier est généré par uv. De la même manière, il est préférable de ne pas copier le dossier .venv pour partager un projet. Dans un dépôt Git, on conserve généralement le code, pyproject.toml et uv.lock, mais pas .venv. Un fichier .gitignore créé par uv aide à ignorer ce dossier.

Cette organisation peut paraître plus structurée qu’un simple pip install, mais elle vous rend service dès que vous avez deux projets, que vous réinstallez votre machine ou que vous envoyez votre code à quelqu’un.

Quand choisir uv, pip ou un environnement virtuel classique

uv est pratique, mais pip n’est pas devenu inutile. Les trois notions ne s’opposent pas complètement : elles répondent à des usages différents.

Utiliser uv pour démarrer un projet personnel

uv est un bon choix si vous créez un nouveau projet, si vous voulez ajouter des bibliothèques proprement et si vous souhaitez éviter de gérer séparément la création de l’environnement virtuel. Les commandes uv init, uv add et uv run constituent un parcours facile à retenir.

C’est aussi une solution intéressante lorsque vous suivez un tutoriel moderne qui fournit un fichier pyproject.toml et un fichier uv.lock.

Utiliser pip quand un tutoriel ou un projet le demande

pip est l’installateur historique le plus répandu dans l’écosystème Python. Beaucoup de documentations indiquent encore :

pip install nom-du-paquet

Vous pouvez suivre cette instruction, idéalement dans un environnement virtuel. Il n’y a aucune erreur à apprendre pip : comprendre cette commande reste utile pour lire des tutoriels, travailler sur des projets existants et dépanner une installation.

Utiliser venv pour apprendre ou garder une méthode minimale

venv est un module fourni avec Python pour créer des environnements virtuels. Une approche classique consiste à créer un environnement, l’activer, puis utiliser pip. Notre article sur la création d’un environnement virtuel avec venv détaille cette méthode.

Elle convient très bien si vous souhaitez comprendre chaque étape ou si votre formation l’utilise déjà. uv automatise une partie de ce travail, mais le principe reste identique : un projet doit disposer de ses propres dépendances.

Les erreurs fréquentes avec uv et comment les éviter

La plupart des difficultés viennent du terminal et du dossier courant, pas de Python lui-même. Voici quelques vérifications simples.

« uv n’est pas reconnu » : rouvrez le terminal après l’installation et vérifiez la procédure officielle pour votre système.
« No module named requests » : lancez uv add requests dans le dossier du projet, puis utilisez uv run main.py.
Le mauvais fichier est exécuté : vérifiez le dossier affiché dans votre terminal avec la commande pwd sur macOS ou Linux, ou avec Get-Location dans PowerShell.
Vous avez installé un paquet globalement par erreur : ce n’est pas grave. Revenez dans votre projet et ajoutez-le avec uv add afin qu’il soit bien déclaré pour ce projet.
Vous ne savez plus quelle commande a été utilisée : ouvrez pyproject.toml. La liste des dépendances du projet est votre repère principal.

Enfin, ne confondez pas une erreur d’installation avec une erreur dans le programme. Une SyntaxError, une NameError ou une erreur de logique dans vos conditions ne sont pas causées par uv. Pour apprendre à identifier la source d’un problème, consultez notre guide pour lire un traceback Python.

Conclusion : adopter une routine simple avec uv

uv permet de commencer un projet Python dans un cadre propre sans multiplier les manipulations. Créez le projet avec uv init, ajoutez une bibliothèque avec uv add, puis exécutez votre code avec uv run. Ces trois commandes couvrent déjà de nombreux besoins d’apprentissage.

pip et venv restent des outils parfaitement valables, notamment pour les projets existants et les tutoriels qui les utilisent. Mais pour un nouveau projet personnel, uv offre une approche claire : les bibliothèques restent liées au dossier où vous en avez besoin, et leur liste est enregistrée avec votre code.

Pour progresser, créez maintenant un petit projet, ajoutez une bibliothèque qui vous intrigue et testez-la dans un fichier Python. Cette pratique concrète est la meilleure façon de rendre les outils Python moins intimidants.