Le parcours ingénieur IA, et les environnements de développement avec uv

Le problème que nous résolvons

Un ingénieur IA rejoint une équipe. La tâche du premier jour est simple : faire tourner le projet sur son propre ordinateur portable. Le README dit « lancez python main.py ». Il lance la commande et obtient ModuleNotFoundError: No module named 'httpx'. Sur la machine de la personne qui a écrit le projet, la même commande marche parfaitement.

En creusant, on découvre que depuis deux ans, tous les paquets dont chaque projet de l'auteur a eu besoin s'accumulent dans le même Python. Les paquets dont ce projet dépend ne sont écrits nulle part — seulement « ça marche sur ma machine ». Le nouveau collègue passe une demi-journée à trouver et à installer les paquets un par un, et à la fin, l'un d'eux est dans une autre version, si bien que les résultats diffèrent aussi.

Les équipes professionnelles ont une seule réponse à ce problème : chaque projet a son propre environnement isolé, et le contenu de cet environnement est écrit dans un fichier, pour que n'importe qui puisse reconstruire exactement le même environnement avec une seule commande. C'est ce que nous construisons dans ce chapitre — avec uv — et c'est ce que nous utiliserons tout au long du cours.

À la fin de ce chapitre vous pourrez

• Installer Python avec l'installeur classique et avec uv python install, et expliquer en quoi les deux diffèrent
• Expliquer ce qu'est pip et pourquoi ce cours utilise uv à la place
• Créer et lancer un environnement de projet isolé avec uv init, uv add, uv run et uv venv
• Montrer, avec un exemple, pourquoi les projets ne doivent pas tourner sur le Python du système
• Sélectionner l'interpréteur propre au projet dans VS Code ou PyCharm

Ce qu'il vous faut d'abord : savoir changer de dossier dans un terminal (cd) et lancer une commande. C'est le premier chapitre du cours, donc rien d'autre n'est nécessaire.

Comment fonctionne ce parcours

Ce cours est un parcours orienté carrière. Chaque chapitre ressemble à un cours en classe, et chacun se termine par une tâche à faire sur votre propre machine. Les premiers chapitres posent les bases du travail professionnel — environnements, Git, structure de projet, configuration. Viennent ensuite le Python propre, les tests, les API, les bases de données, RAG, la sécurité et le déploiement.

Un point à dire d'emblée : dans une entreprise, le code d'un ingénieur IA n'est pas accepté simplement parce qu'il « tourne ». Que quelqu'un d'autre puisse le lancer sur sa machine, qu'il puisse être relu, que quelqu'un le comprenne encore dans six mois — ces points font aussi partie du métier. C'est pourquoi chaque tâche pratique de ce cours est conçue comme si elle allait dans le dépôt d'une vraie équipe. Et la première étape de cette habitude, c'est l'environnement.

Installer Python : deux méthodes

Première méthode — l'installeur classique. Téléchargez l'installeur 3.12 sur python.org et lancez-le. Sous Windows, cochez Add python.exe to PATH dès le tout premier écran ; sans cela, le terminal ne reconnaîtra pas la commande python. Sous macOS, lancer le .pkg de python.org suffit. Sous Linux, python3 est généralement déjà présent — et il y a un avertissement à ce sujet plus bas.

Pour vérifier :

python --version
Python 3.12.0

Sous macOS et Linux, la commande est souvent python3 --version.

Deuxième méthode — avec uv. uv est un outil unique qui gère les versions de Python, les environnements de projet et les paquets. Installez d'abord uv. Sous macOS et Linux :

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

Dans Windows PowerShell :

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

Ensuite, ouvrez un nouveau terminal :

uv --version
uv 0.9.1 (9887ef5bd 2025-10-09)

Votre numéro de version peut être différent. Installons maintenant Python :

uv python install 3.12
Installed Python 3.12.11 in 27.42s
 + cpython-3.12.11-windows-x86_64-none (python3.12.exe)

La durée et le nom de la plateforme, à la fin, seront différents sur votre machine. Remarquez que le Python installé par uv se trouve dans un dossier à part : il ne touche pas au Python principal de la machine et ne modifie pas le PATH.

Les deux méthodes peuvent coexister, et les deux fonctionnent pour ce cours. La différence : l'installeur classique vous donne un seul Python pour tout l'ordinateur ; uv python install vous donne des Python que chaque projet choisit selon ses besoins. Un projet veut la 3.12, un autre la 3.13 — aucun ne gêne l'autre.

Ce qu'est pip, et pourquoi nous utilisons uv

Les paquets externes de Python — httpx, pydantic, fastapi — sont hébergés dans un dépôt appelé PyPI. L'outil traditionnel pour les télécharger est pip, livré avec Python. Presque tous les tutoriels sur Internet écrivent pip install ....

pip fonctionne bien, mais il ne fait qu'une seule chose : installer des paquets. Et il les installe dans le Python avec lequel il a été lancé. Pour un projet professionnel, tout le reste demande un outil séparé :

• choisir la bonne version de Python — un outil séparé
• créer et activer un environnement isolé — python -m venv, puis activate à la main
• consigner ce dont le projet a besoin — à la main, dans un fichier, souvent oublié
• figer la version exacte de chaque paquet utilisée (un lockfile) — encore un autre outil

uv fait les quatre en un seul outil, et beaucoup plus vite. Surtout, quand vous ajoutez quelque chose avec uv add, c'est écrit automatiquement dans le fichier du projet. « Je l'ai installé mais j'ai oublié de le noter » — la cause réelle des ennuis du nouveau collègue plus haut — ne peut pas arriver de cette façon.

Donc, partout où il sera question de paquets ou d'environnements dans ce cours, c'est uv. Si vous voyez pip install ailleurs, l'équivalent avec uv est presque toujours uv add.

Pourquoi le Python du système n'est pas fait pour les projets

Le « Python du système » est le Python installé directement sur l'ordinateur — celui qui se lance quand vous tapez python dans un terminal sans avoir activé d'environnement. Installer les paquets d'un projet dedans pose trois problèmes :

1. Tout le monde partage la même pièce. Un projet a besoin de pydantic 1, un autre de pydantic 2. Le Python du système ne peut en contenir qu'un : réparer un projet casse donc l'autre.
2. Les dépendances deviennent invisibles. Le paquet était déjà installé pour un vieux projet ; le nouveau projet tourne donc — mais nulle part dans le projet il n'est dit qu'il a besoin de ce paquet. Aucune erreur n'apparaît sur votre machine ; l'erreur apparaît sur celle d'un collègue, ou sur le serveur.
3. Le système d'exploitation s'en sert. Sous macOS et Linux, certains outils système tournent avec ce Python. Modifier ses paquets peut les casser — c'est pourquoi les versions récentes de Linux bloquent l'installation directe dans le Python du système.

Le deuxième problème est le plus dangereux, car il est silencieux. Le Python du système de la machine sur laquelle ce chapitre a été écrit contient encore httpx, pydantic et rich, restes de vieux travaux. Donc n'importe quel script « tourne » là-bas — et c'est précisément pour cela qu'on ne peut pas savoir, à partir de là, ce dont un script a vraiment besoin.

La fausse croyance : « Ça tourne sur ma machine, donc c'est bon. » Un script qui tourne sur le Python du système prouve seulement qu'à un moment donné, le paquet a été installé sur votre machine. Ce dont le projet a vraiment besoin, on ne le prouve que lorsque tout est installé dans un environnement vide, à partir du fichier du projet lui-même, puis en lançant le script.

Un premier projet avec uv

Depuis un dossier de travail :

uv init hello-ai --python 3.12
Initialized project `hello-ai` at `D:\ai-lab\hello-ai`

(Le chemin à la fin sera celui de votre propre dossier ; les extraits de ce chapitre raccourcissent les chemins.) uv init crée un nouveau dossier, et à l'intérieur :

hello-ai/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Le plus important de ces fichiers est pyproject.toml — la carte d'identité du projet :

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

dependencies = [] — le projet n'a encore besoin d'aucun paquet externe. .python-version ne contient que 3.12 : le Python sur lequel tourne ce projet. Et uv init a aussi créé pour vous un dépôt Git et un .gitignore — ils serviront dans le prochain chapitre.

Lancez-le maintenant :

cd hello-ai
uv run main.py
Using CPython 3.12.11
Creating virtual environment at: .venv
Hello from hello-ai!

La première fois, uv run a créé tout seul un dossier .venv — c'est l'environnement isolé du projet — puis a lancé main.py avec le Python de cet environnement. Vous n'avez rien eu à activer.

uv add : ajouter un paquet, et le noter

Presque tous les projets sur lesquels travaille un ingénieur IA appellent une API. Le premier paquet sera donc le client HTTP httpx, avec python-dotenv pour lire les fichiers .env :

uv add httpx python-dotenv
Resolved 9 packages in 119ms
Installed 8 packages in 92ms
 + anyio==4.15.1
 + certifi==2026.7.22
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.20
 + python-dotenv==1.2.3
 + typing-extensions==4.16.0

Vous avez demandé deux paquets et en avez obtenu huit — les autres sont les dépendances de httpx elles-mêmes, que uv a déterminées tout seul. Les numéros de version peuvent être plus récents quand vous faites cette étape.

Regardez maintenant pyproject.toml :

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.28.1",
    "python-dotenv>=1.2.3",
]

Une seule commande a fait trois choses : les paquets ont été installés dans .venv, pyproject.toml enregistre maintenant que le projet en a besoin, et un nouveau fichier nommé uv.lock est apparu, figeant la version exacte des huit paquets. Le lockfile sera étudié plus en détail un peu plus loin dans le cours ; pour l'instant, il suffit de savoir qu'un collègue qui clone le dépôt et lance uv sync obtient exactement ces huit versions.

Pour retirer un paquet, on utilise uv remove :

uv remove python-dotenv
Resolved 8 packages in 21ms
Uninstalled 1 package in 11ms
 - python-dotenv==1.2.3

Cela agit aussi aux deux endroits : il retire le paquet de .venv et le supprime de pyproject.toml.

uv venv, et l'activation à la main

uv run crée et utilise l'environnement à votre place, donc dans ce cours, il suffit presque toujours. Parfois, cependant, il vous faut simplement un environnement vide — par exemple dans un vieux projet qui n'a pas encore de pyproject.toml. Dans ce cas :

uv venv --python 3.12
Using CPython 3.12.11
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

La dernière ligne vient de Windows PowerShell. C'est là que les systèmes d'exploitation diffèrent :

# Windows (PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Une fois activé, l'invite commence par (hello-ai) ou (.venv), et une simple commande python lance le Python de cet environnement. Pour en sortir, deactivate. Rappelez-vous qu'avec uv run, rien de tout cela n'est nécessaire — c'est son avantage, et écrire uv run dans le README d'une équipe est le choix sûr, car il n'existe pas d'état « j'ai oublié d'activer ».

Indiquer à l'éditeur le Python du projet

Le programme tourne dans le terminal, mais l'éditeur souligne import httpx en rouge — cela signifie presque toujours que l'éditeur regarde un autre Python.

VS Code : installez l'extension Python de Microsoft. Ouvrez ensuite le dossier du projet, appuyez sur Ctrl + Shift + P (Cmd + Shift + P sous macOS) → Python: Select Interpreter → choisissez le Python qui se trouve dans .venv. S'il n'apparaît pas dans la liste, utilisez Enter interpreter path et indiquez-le : .venv\Scripts\python.exe sous Windows, .venv/bin/python sous macOS/Linux.

PyCharm : Settings → Project → Python Interpreter → Add Interpreter → Add Local Interpreter → choisissez un environnement existant et indiquez le même chemin. Les versions récentes proposent aussi directement un type d'environnement uv.

Le moyen simple de savoir quel Python utilise l'éditeur est de lancer ceci dans le terminal intégré de l'éditeur :

import sys

print(sys.executable)

Le chemin doit se terminer à l'intérieur du .venv de votre projet — par exemple ...\hello-ai\.venv\Scripts\python.exe. Le début du chemin dépend de votre dossier, c'est pourquoi la sortie complète n'est pas affichée ici.

Un exemple complet

Dans le projet hello-ai, créez un fichier nommé env_check.py. C'est un petit script de « vérification de l'environnement » — quand quelqu'un rejoint une équipe, lancer ce genre de script en premier confirme que tout est bien en place :

import sys
from importlib.metadata import version
from pathlib import Path


def main() -> None:
    in_venv = sys.prefix != sys.base_prefix
    print(f"Python      : {sys.version_info.major}.{sys.version_info.minor}")
    print(f"In a venv   : {in_venv}")
    print(f"Env folder  : {Path(sys.prefix).name}")

    import httpx  # installed with `uv add httpx`

    print(f"httpx       : {version('httpx')}")
    print(f"Client ready: {httpx.Client is not None}")
    print("Hello, AI engineer.")


if __name__ == "__main__":
    main()

Lancez-le depuis l'intérieur du projet :

uv run env_check.py

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

Lançons maintenant le même fichier dans un environnement vide. Le fichier a été copié dans un autre dossier, un environnement y a été créé avec uv venv --python 3.12, puis le fichier a été lancé directement avec le Python de cet environnement (.venv\Scripts\python env_check.py sous Windows, .venv/bin/python env_check.py sous macOS/Linux) :

Python      : 3.12
In a venv   : True
Env folder  : .venv
Traceback (most recent call last):
  File "env_check.py", line 20, in <module>
    main()
  File "env_check.py", line 12, in main
    import httpx  # installed with `uv add httpx`
    ^^^^^^^^^^^^
ModuleNotFoundError: No module named 'httpx'

(Sur votre machine, le traceback affiche le chemin complet du fichier ; seul le nom est conservé ici.)

Quelques choix de ce script méritent d'être remarqués.

sys.prefix != sys.base_prefix — Python sait lui-même s'il tourne dans un environnement virtuel. sys.base_prefix est le Python de base à partir duquel l'environnement a été créé, et sys.prefix est celui qui tourne actuellement. S'ils diffèrent, vous êtes dans un environnement.

Le nom du dossier, pas le chemin complet — Path(sys.prefix).name n'affiche que la dernière partie, .venv. Le chemin complet est différent sur chaque machine ; le nom est le même pour tout le monde. Moins la sortie d'un script de vérification dépend de la machine, plus il est facile de la comparer dans le chat de l'équipe.

import httpx au milieu de la fonction — les imports vont normalement en haut d'un fichier, et doivent y aller. Ici, il est volontairement placé au milieu, pour que, dans un environnement vide, les trois premières lignes s'affichent avant l'erreur. La sortie d'erreur raconte alors sa propre histoire : Python 3.12 va bien, un environnement est actif, mais cet environnement n'a pas httpx. La solution est uv add httpx — ou, si le pyproject.toml du projet le liste déjà, uv sync.

version('httpx') — importlib.metadata est la façon standard de lire la version d'un paquet. Tous les paquets n'ont pas de __version__, mais tout paquet installé a des métadonnées.

Quand ça casse

The term 'uv' is not recognized as the name of a cmdlet, function, script file, or operable program (sous macOS/Linux, uv: command not found) uv est bien installé, mais le terminal dans lequel vous tapez a été ouvert avant l'installation, donc il ne connaît pas le nouveau PATH. Fermez et rouvrez le terminal (et, dans VS Code, fermez et rouvrez tout l'éditeur).

error: No pyproject.toml found in current directory or any parent directory Vous avez lancé uv add en dehors d'un dossier de projet. uv add écrit dans le fichier du projet ; sans projet, il n'y a nulle part où écrire. Placez-vous dans le dossier du projet avec cd, ou lancez d'abord uv init si le projet est nouveau.

ModuleNotFoundError: No module named 'httpx' Le Python qui exécute le script n'a pas ce paquet. Deux causes fréquentes : le paquet n'a jamais été ajouté avec uv add, ou le script a été lancé avec un simple python au lieu de uv run, si bien que c'est le Python du système qui a tourné à la place de l'environnement du projet. Lancez-le avec uv run env_check.py.

error: Failed to spawn: hello.py suivi de Caused by: program not found Vous avez donné à uv run un nom de fichier qui ne se trouve pas dans le dossier courant — en général une faute de frappe, ou vous êtes dans le mauvais dossier. Ne trouvant pas le fichier, uv a cherché un programme portant ce nom à la place, ce qui explique le message étrange.

× No solution found when resolving dependencies suivi de Because htpx was not found in the package registry ... Une faute de frappe dans le nom du paquet (htpx). Bonne nouvelle : un uv add raté ne modifie rien — pyproject.toml et uv.lock restent tels quels. Corrigez l'orthographe et relancez la commande.

.venv\Scripts\activate : File ... cannot be loaded because running scripts is disabled on this system Une règle de sécurité de PowerShell. Lancez une fois Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, puis ouvrez un nouveau terminal — ou bien ne faites pas d'activation et lancez tout avec uv run.

À vous de jouer

Une fois uv et Python 3.12 prêts sur votre machine, créez un nouveau projet :

1. Créez le projet avec uv init my-first-agent --python 3.12, et ajoutez un paquet avec uv add httpx
2. Écrivez le fichier env_check.py ci-dessus dans le projet, à l'identique, et lancez-le avec uv run env_check.py
3. Ouvrez pyproject.toml et vérifiez que httpx figure sous dependencies, et qu'un fichier uv.lock a été créé dans le projet
4. Ouvrez le projet dans VS Code ou PyCharm et sélectionnez le .venv du projet comme interpréteur, pour qu'il n'y ait plus de soulignement rouge sur la ligne import httpx

Sortie attendue (la version de httpx peut être plus récente quand vous faites cette étape) :

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

Ensuite, cassez-le volontairement : lancez uv remove httpx, puis relancez uv run env_check.py. Notez jusqu'où le script affiche, quelle erreur apparaît et ce qui a changé dans pyproject.toml. Réparez ensuite avec uv add httpx. Cette boucle casser-réparer prend deux minutes, mais pendant la première semaine de votre premier emploi, c'est ce qui vous fera gagner le plus de temps.