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 :
- installer d’abord les dépendances Conda ;
- installer ensuite avec
pip uniquement les paquets absents de Conda ;
- éviter de réinstaller via
pip une bibliothèque native déjà gérée par Conda.
