Partie 10 — pyproject.toml

38. Le fichier central des projets modernes

Exemple :

[project]
name = "mon-projet"
version = "0.1.0"
description = "Exemple"
requires-python = ">=3.12,<3.13"

dependencies = [
    "fastapi>=0.115,<1",
    "sqlalchemy>=2,<3",
    "psycopg[binary]>=3.2,<4",
]

[project.optional-dependencies]
dev = [
    "pytest>=8",
    "ruff>=0.12",
    "mypy>=1.16",
]

Installation du projet :

python -m pip install .

Installation en mode éditable :

python -m pip install -e .

Avec les dépendances de développement :

python -m pip install -e ".[dev]"

39. Mode éditable

Avec :

python -m pip install -e .

le projet local est installé de manière à ce que les changements de code soient immédiatement visibles sans réinstallation complète.

C’est le mode habituel pour développer une bibliothèque ou une application structurée comme un paquet Python.

40. Build backend

Exemple utilisant setuptools :

[build-system]
requires = ["setuptools>=75", "wheel"]
build-backend = "setuptools.build_meta"

Exemple avec Hatchling :

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Exemple avec uv_build :

[build-system]
requires = ["uv_build"]
build-backend = "uv_build"

Le backend est l’outil chargé de construire la distribution du projet.

Partie 11 — Installer plusieurs versions de Python

41. Sous Windows : utiliser le lanceur py

Lister les versions :

py --list

Créer un environnement en Python 3.11 :

py -3.11 -m venv .venv

Créer un environnement en Python 3.12 :

py -3.12 -m venv .venv

Exécuter un script avec une version précise :

py -3.11 script.py

Installer un paquet dans le Python global 3.12 :

py -3.12 -m pip install package

Mais pour un projet, on préférera :

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install package

42. Sous Linux : ne pas remplacer le Python système

Éviter de modifier manuellement :

/usr/bin/python3

Éviter également de supprimer le Python installé par la distribution.

Les outils système peuvent dépendre d’une version précise.

Approches recommandées :

• paquets officiels de la distribution ;
• pyenv ;
• uv ;
• conteneurs Docker ;
• compilation dans /opt ou dans le dossier utilisateur ;
• environnements virtuels.

43. pyenv

pyenv permet de gérer plusieurs interpréteurs Python.

Commandes typiques :

pyenv install 3.11.11
pyenv install 3.12.10
pyenv versions
pyenv local 3.12.10

Le fichier :

.python-version

peut contenir :

3.12.10

pyenv sélectionne alors cette version dans le répertoire du projet.

Important : pyenv choisit l’interpréteur, mais ne gère pas à lui seul toutes les dépendances du projet.

On peut l’associer à venv :

pyenv local 3.12.10
python -m venv .venv

Partie 12 — uv, approche moderne recommandée

44. Qu’est-ce que uv ?

uv est un gestionnaire Python et de projets écrit en Rust. Il peut notamment :

• installer plusieurs versions de Python ;
• créer les environnements virtuels ;
• résoudre les dépendances ;
• installer les paquets ;
• créer un fichier de verrouillage ;
• lancer des commandes ;
• gérer des outils CLI isolés.

La documentation officielle le présente comme un gestionnaire de paquets et de projets Python rapide.

45. Gérer Python avec uv

Lister les versions :

uv python list

Installer Python 3.12 :

uv python install 3.12

Trouver l’interpréteur :

uv python find 3.12

Fixer la version du projet :

uv python pin 3.12

Cela crée généralement :

.python-version

uv sait installer, lister, trouver, fixer et désinstaller des versions de Python.

46. Créer un projet avec uv

uv init mon-projet
cd mon-projet
uv python pin 3.12
uv add fastapi
uv add sqlalchemy
uv add --dev pytest ruff

Structure possible :

mon-projet/
├── .python-version
├── .venv/
├── pyproject.toml
├── uv.lock
└── src/

Le fichier .python-version indique la version Python par défaut du projet, tandis que .venv contient son environnement isolé.

47. Synchroniser l’environnement

uv sync

Cette commande crée ou met à jour .venv selon :

pyproject.toml
uv.lock

Lancer le projet :

uv run python main.py

Lancer les tests :

uv run pytest

Il n’est pas obligatoire d’activer manuellement .venv.

48. Ajouter et retirer des dépendances

uv add requests
uv add "django>=5,<6"
uv add --dev pytest
uv remove requests

uv met à jour :

• pyproject.toml ;
• uv.lock ;
• l’environnement.

49. Pourquoi uv simplifie le problème

Avec la méthode historique, on doit coordonner :

installation Python
+ venv
+ pip
+ requirements.txt
+ éventuellement pip-tools
+ éventuellement pipx

Avec uv, on peut coordonner :

version Python
+ environnement
+ dépendances
+ lockfile
+ commandes

Workflow recommandé :

uv init
uv python pin 3.12
uv add fastapi
uv add --dev pytest
uv run pytest

Partie 13 — pipx et outils en ligne de commande

50. Pourquoi ne pas installer les CLI globalement ?

Des outils comme :

• black ;
• ruff ;
• poetry ;
• httpie ;
• cookiecutter ;
• ansible ;

sont des applications Python, pas forcément des dépendances d’un projet.

Les installer globalement peut provoquer des conflits.

pipx installe chaque outil dans son propre environnement virtuel tout en exposant sa commande dans le PATH.

Exemple :

pipx install poetry
pipx install httpie
pipx list
pipx upgrade-all

Avec uv :

uv tool install ruff
uv tool install httpie
uvx ruff check .

Chaque outil géré par uv est lié à une version précise de Python et dispose de son environnement isolé.

Partie 14 — Erreurs fréquentes et diagnostic

51. ModuleNotFoundError

Erreur :

ModuleNotFoundError: No module named 'requests'

Vérifications :

python -c "import sys; print(sys.executable)"
python -m pip show requests
python -m pip list

Puis :

python -m pip install requests

Ne pas se contenter de :

pip install requests

car ce pip peut appartenir à un autre Python.

52. pip n’est pas reconnu

Sous Windows :

py -m pip --version

Si cela fonctionne, utiliser :

py -m pip install package

Dans un environnement virtuel :

python -m pip install package

Si pip manque :

python -m ensurepip --upgrade

Puis :

python -m pip install --upgrade pip

53. Mauvaise version de Python

Erreur :

Package requires Python >=3.11

Diagnostic :

python --version
python -c "import sys; print(sys.executable)"

Solution Windows :

py -3.12 -m venv .venv

Solution Linux avec un Python déjà installé :

python3.12 -m venv .venv

Un environnement existant en Python 3.10 ne peut pas être transformé proprement en environnement Python 3.12.

Il faut le recréer.

54. No matching distribution found

Exemple :

ERROR: Could not find a version that satisfies the requirement package
ERROR: No matching distribution found

Causes possibles :

• nom du paquet incorrect ;
• version inexistante ;
• Python trop ancien ;
• Python trop récent ;
• architecture non supportée ;
• absence de wheel et source indisponible ;
• index privé mal configuré ;
• préversion ignorée ;
• paquet retiré ;
• contraintes incompatibles.

Diagnostic :

python --version
python -m pip index versions package
python -m pip install -vvv package

Pour autoriser une préversion :

python -m pip install --pre package

55. ResolutionImpossible

Lancer :

python -m pip install -vvv -r requirements.txt

Puis rechercher les contraintes contradictoires.

Exemple :

A demande urllib3<2
B demande urllib3>=2

Solutions possibles :

• mettre à jour A ;
• mettre à jour B ;
• rétrograder l’un des paquets ;
• remplacer une bibliothèque ;
• utiliser une version de Python plus adaptée ;
• corriger une contrainte trop stricte.

Éviter de contourner aveuglément avec :

--no-deps

Cette option installe le paquet sans ses dépendances et peut créer un environnement incohérent.

56. Failed building wheel

Diagnostic :

python -m pip install -vvv package

Tester l’existence d’un binaire :

python -m pip install --only-binary=:all: package

Si aucune distribution n’est trouvée, il n’existe probablement pas de wheel compatible.

Choix possibles :

• installer les outils de compilation ;
• utiliser une autre version de Python ;
• utiliser une autre architecture ;
• attendre une wheel ;
• utiliser une version antérieure du paquet ;
• utiliser Conda pour les bibliothèques scientifiques complexes ;
• construire une wheel sur une machine de build.

57. externally-managed-environment

Sur certaines distributions Linux :

error: externally-managed-environment

Cela signifie que le Python système est administré par le gestionnaire de paquets de la distribution.

Bonne solution :

python3 -m venv .venv
source .venv/bin/activate
python -m pip install package

Pour une application CLI :

pipx install outil

ou :

uv tool install outil

Éviter :

sudo pip install ...

et éviter autant que possible :

--break-system-packages

car cette option autorise précisément la modification risquée de l’environnement système.

58. Le paquet est installé mais VS Code ne le voit pas

VS Code utilise peut-être un autre interpréteur.

Dans VS Code :

Ctrl + Shift + P
Python: Select Interpreter

Choisir :

...\projet\.venv\Scripts\python.exe

ou :

.../projet/.venv/bin/python

Vérification dans le terminal intégré :

python -c "import sys; print(sys.executable)"

Le terminal, le débogueur, les notebooks Jupyter et l’analyseur de code peuvent chacun utiliser un interpréteur différent.

Partie 15 — Jupyter et environnements

59. Le piège des kernels

Un notebook peut afficher un environnement différent du terminal.

Dans une cellule :

import sys
print(sys.executable)

Pour enregistrer l’environnement comme kernel :

python -m pip install ipykernel
python -m ipykernel install --user --name mon-projet --display-name "Python - mon-projet"

Dans Jupyter, sélectionner ensuite :

Python - mon-projet

Pour installer depuis le notebook, préférer :

import sys
!{sys.executable} -m pip install requests

ou, dans les environnements Jupyter compatibles :

%pip install requests

plutôt que :

!pip install requests

qui peut appeler un autre pip.

Partie 16 — Paquets, modules, distributions : trois notions différentes

60. Distribution PyPI versus module importé

Le nom installé et le nom importé peuvent différer.

Exemples :

python -m pip install pillow

Puis :

from PIL import Image

Autre exemple :

python -m pip install beautifulsoup4

Puis :

from bs4 import BeautifulSoup

Autre exemple :

python -m pip install scikit-learn

Puis :

import sklearn

Il faut distinguer :

• le nom de distribution ;
• le nom du module ;
• le nom du paquet Python ;
• le nom de la commande CLI.

61. Vérifier à quelle distribution appartient un module

python -m pip show pillow

En Python :

import PIL
print(PIL.__file__)

Pour lire les métadonnées :

from importlib.metadata import version

print(version("pillow"))

Partie 17 — Architecture et système d’exploitation

62. Vérifier l’architecture

python -c "import platform; print(platform.machine())"

Sous Windows :

python -c "import struct; print(struct.calcsize('P') * 8)"

Résultat :

64

indique un Python 64 bits.

Il est possible d’avoir :

• Windows 64 bits ;
• mais Python 32 bits.

Dans ce cas, seules les wheels win32 seront acceptées, pas les wheels win_amd64.

63. ARM contre x86-64

Architectures courantes :

x86_64
AMD64
aarch64
arm64

Exemples :

• PC Intel/AMD Windows : généralement AMD64 ;
• serveur DigitalOcean classique : souvent x86_64 ;
• Mac Apple Silicon : arm64 ;
• Raspberry Pi 64 bits : aarch64.

Une wheel x86-64 ne s’installe pas nativement sur ARM64.

64. Linux glibc contre musl

De nombreuses distributions Linux utilisent glibc.

Alpine Linux utilise généralement musl.

Une wheel :

manylinux_2_17_x86_64

vise un environnement Linux compatible glibc.

Une wheel :

musllinux_1_2_x86_64

vise musl.

C’est pourquoi les images Docker Alpine provoquent parfois davantage de compilations natives que les images Debian slim.

Pour des projets Python contenant beaucoup de dépendances natives, cette image est souvent plus simple :

FROM python:3.12-slim

qu’une image :

FROM python:3.12-alpine

Partie 18 — Conda et bibliothèques scientifiques

65. Quand utiliser Conda ?

pip installe principalement des distributions Python.

Conda peut gérer :

• Python ;
• les paquets Python ;
• les bibliothèques système ;
• des outils natifs ;
• CUDA ;
• BLAS ;
• certains compilateurs.

Conda peut être pertinent pour :

• data science ;
• calcul scientifique ;
• géospatial ;
• bio-informatique ;
• environnements CUDA complexes ;
• dépendances natives difficiles.

Exemple :

conda create -n projet python=3.12
conda activate projet
conda install numpy pandas scipy

Éviter de mélanger sans stratégie :

conda install
pip install

Approche prudente :

1. installer d’abord les dépendances Conda ;
2. installer ensuite avec pip uniquement les paquets absents de Conda ;
3. éviter de réinstaller via pip une bibliothèque native déjà gérée par Conda.