Python : environnements virtuels

Un environnement virtuel est un dossier qui contient un interpréteur et ses propres paquets : chaque projet a ses dépendances, sans toucher au système.

Créer et activer avec venv

sudo apt install python3-venv           # une seule fois
cd monprojet
python3 -m venv .venv
source .venv/bin/activate
which python                            # .../monprojet/.venv/bin/python
python --version
deactivate                              # quitter l'environnement

Le dossier .venv/ ne se versionne pas (.gitignore : .venv/). Il se recrée à tout moment.

Installer des paquets

source .venv/bin/activate
pip install requests
pip install "flask>=3,<4"
pip list
pip show requests
pip uninstall requests

Sans activer l’environnement, appeler directement son interpréteur :

.venv/bin/python script.py
.venv/bin/pip install requests

C’est la forme à utiliser dans les scripts, les tâches planifiées et les services systemd.

Figer les dépendances

pip freeze > requirements.txt
pip install -r requirements.txt

pip freeze liste toutes les versions installées, y compris les dépendances indirectes : adapté au déploiement reproductible. Pour un fichier lisible, déclarer seulement les dépendances directes dans requirements.in ou pyproject.toml.

pyproject.toml

Format moderne de description d’un projet :

[project]
name = "monapp"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "flask>=3,<4",
    "requests>=2.32",
]

[project.optional-dependencies]
dev = ["pytest", "ruff"]

pip install -e .            # installe le projet en mode éditable
pip install -e ".[dev]"     # avec les dépendances de développement

uv : une alternative rapide

uv remplace pip et venv avec un résolveur très rapide :

sudo apt install pipx
pipx install uv
uv venv
uv pip install requests
uv pip install -r requirements.txt

Avec un pyproject.toml, uv gère aussi le verrouillage :

uv init monprojet
cd monprojet
uv add requests
uv add --dev pytest
uv sync                      # crée .venv et installe selon uv.lock
uv run python script.py      # exécute dans l'environnement

Versionner pyproject.toml et uv.lock.

pipx : installer des outils en ligne de commande

sudo apt install pipx
pipx ensurepath                          # ajoute ~/.local/bin au PATH (rouvrir le terminal)
pipx install httpie
pipx list
pipx upgrade-all
pipx uninstall httpie

pipx crée un environnement isolé par outil : les outils ne se gênent pas et ne touchent pas au système.

Bonnes pratiques

Un environnement par projet, dans .venv/ à la racine.
Ne jamais utiliser sudo pip.
Figer les versions (requirements.txt ou verrou uv.lock) et les versionner.
Préciser la version de Python visée (requires-python).
Recréer l’environnement après un changement de version majeure de Python : un venv est lié à l’interpréteur qui l’a créé.

rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Dépannage

Symptôme	Piste
`ensurepip is not available`	`sudo apt install python3-venv`
`externally-managed-environment`	Pip lancé hors d’un venv : l’activer ou utiliser `.venv/bin/pip`
`pip` installe dans le système	Environnement non actif : `which pip`
`bad interpreter` après une montée de version d’Ubuntu	Le venv pointe vers l’ancien Python : le recréer
Un paquet ne compile pas	`sudo apt install build-essential python3-dev` et les bibliothèques de développement nécessaires
`command not found` après `pipx install`	`pipx ensurepath`, puis rouvrir le terminal

Ubuntu 24.04 et 26.04 : différences à connaître

Les commandes sont identiques. Après une mise à niveau de 24.04 vers 26.04 (Python 3.12 vers 3.14), les environnements virtuels existants doivent être recréés.

Pour aller plus loin

Module venv
Suite : Gestion des paquets