Python venv : création, activation, requirements.txt et exploitation en production

EdwardMoon

Python venv sépare l'espace d'installation des paquets de chaque projet. Il fait partie de la bibliothèque standard Python. Installer directement des paquets dans le Python système peut provoquer des conflits avec les outils du système ou d'autres applications ; les environnements virtuels permettent à chaque projet de gérer ses versions indépendamment.

Ce guide pratique couvre la création et la vérification des environnements sous Linux, macOS et Windows, puis la gestion de requirements.txt, des wheelhouses hors ligne, des services systemd, de la suppression sécurisée et des incidents. Avant de copier les commandes, adaptez la version de Python et les chemins à votre environnement.

Démarrage rapide avec Python venv

La méthode la plus simple consiste à créer .venv dans le répertoire du projet et à exécuter pip via le Python de cet environnement. Utiliser python -m pip plutôt que pip seul permet de savoir précisément à quel interpréteur pip appartient.

mkdir -p ~/projects/sample-app
cd ~/projects/sample-app

python3 --version
python3 -m venv .venv
source .venv/bin/activate

python -m pip --version
python -m pip install --upgrade pip
python -m pip install requests
python -c "import requests; print(requests.__version__)"

deactivate

Ce qu'est venv et ce qu'il isole

Un contexte d'exécution distinct, pas une copie complète de Python

Créer un environnement virtuel ajoute pyvenv.cfg, un répertoire d'exécutables et un répertoire site-packages distinct à l'emplacement cible. Selon la plateforme et les options, l'exécutable Python est copié ou lié symboliquement. venv n'isole donc pas le système comme un conteneur : il dépend du Python ayant servi à sa création et des bibliothèques du système.

python3 -m venv .venv

find .venv -maxdepth 2 -type f -o -type l | sort | head -30
cat .venv/pyvenv.cfg

Vérifier de manière fiable l'utilisation d'un environnement virtuel

Le script d'activation place le répertoire d'exécutables de l'environnement en tête de PATH. L'activation étant facultative, vérifier uniquement VIRTUAL_ENV ne couvre pas tous les cas. Dans Python, comparer sys.prefix à sys.base_prefix est plus fiable.

python - <<'PY'
import sys

print("executable   :", sys.executable)
print("prefix       :", sys.prefix)
print("base_prefix  :", sys.base_prefix)
print("inside venv  :", sys.prefix != sys.base_prefix)
PY

Vérifications avant la création

Identifiez d'abord l'exécutable Python exact et sa version, puis vérifiez la disponibilité du module venv et de l'amorçage de pip. Si plusieurs versions coexistent, choisissez explicitement l'interpréteur à la création, par exemple python3.11.

command -v python3
python3 --version
python3 -m venv --help >/dev/null
python3 -m ensurepip --version

Certaines distributions Linux fournissent venv ou pip dans des paquets séparés. Leurs noms dépendent de la distribution et de la version de Python : vérifiez les dépôts avant installation. Évitez sudo pip install avec le Python système.

# Exemple courant pour Debian et Ubuntu
sudo apt update
sudo apt install python3-venv python3-pip

# Sous RHEL et Rocky, vérifier d'abord les paquets disponibles
sudo dnf list --available 'python3*' | grep -E 'pip|virtualenv'

Création et activation selon le système et le shell

Après activation, vérifiez le chemin et la version. Le préfixe (.venv) de l'invite n'est qu'un indicateur pratique ; contrôler le véritable chemin de l'interpréteur évite d'installer les paquets au mauvais endroit.

command -v python
python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

Utiliser un venv sans l'activer

Il n'est pas nécessaire d'exécuter source pour utiliser un venv. Dans cron, systemd ou la CI, appeler le chemin absolu du Python de l'environnement est plus prévisible et plus facile à diagnostiquer qu'un script d'activation.

# Linux/macOS
/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
/opt/sample-app/.venv/bin/python -m pip list

# Windows PowerShell
.\.venv\Scripts\python.exe .\app.py

Installer les paquets et gérer requirements.txt

Toujours exécuter pip via le Python souhaité

python -m pip install --upgrade pip
python -m pip install 'requests>=2.32,<3'
python -m pip list
python -m pip check

pip check vérifie la compatibilité des dépendances déclarées par les paquets installés. Exécutez-le avec les tests applicatifs après installation pour repérer rapidement les dépendances manquantes ou incompatibles.

Consigner et reproduire un environnement

pip freeze liste les versions installées des dépendances directes et transitives, ce qui est utile pour consigner un environnement de production. Le même fichier peut ne pas s'installer tel quel sur un autre système, une autre architecture CPU ou une autre version de Python : notez aussi les conditions d'exécution.

python -m pip freeze > requirements.txt
python -m pip check

# Reproduire l'installation dans un nouvel environnement
python3 -m venv .venv-new
.venv-new/bin/python -m pip install --upgrade pip
.venv-new/bin/python -m pip install -r requirements.txt
.venv-new/bin/python -m pip check

Fichiers à conserver dans le projet

# .gitignore
.venv/
__pycache__/
*.py[cod]
.env

# Consigner les versions et les paquets installés
python --version
python -m pip --version
python -m pip freeze

Utiliser Python venv hors ligne ou en réseau isolé

Pour un déploiement hors ligne, reproduisez sur le serveur de préparation le système, l'architecture CPU et les versions majeure et mineure de Python de la cible. Les wheels peuvent dépendre de la plateforme et de l'ABI Python ; une simple copie depuis un autre PC peut donc échouer.

Préparer un wheelhouse sur le serveur connecté

python3 -m venv bundle-venv
bundle-venv/bin/python -m pip install --upgrade pip

# N'autoriser que les wheels permet de repérer les paquets qui exigeraient une compilation hors ligne.
bundle-venv/bin/python -m pip download   --only-binary=:all:   --dest wheelhouse   -r requirements.txt

sha256sum wheelhouse/* > SHA256SUMS
tar -czf python-wheelhouse.tar.gz wheelhouse requirements.txt SHA256SUMS
sha256sum python-wheelhouse.tar.gz > python-wheelhouse.tar.gz.sha256

Vérifier et installer sur le serveur hors ligne

sha256sum -c python-wheelhouse.tar.gz.sha256
tar -xzf python-wheelhouse.tar.gz

sha256sum -c SHA256SUMS

python3 -m venv .venv
.venv/bin/python -m pip install   --no-index   --find-links=wheelhouse   -r requirements.txt
.venv/bin/python -m pip check

Un paquet qui échoue avec --only-binary=:all: ne dispose pas de wheel compatible dans la source choisie. Construisez un wheel sur le serveur connecté avec le compilateur et les en-têtes nécessaires, puis créez un environnement neuf sur un serveur de test identique à la cible et vérifiez l'installation et l'exécution.

Utiliser un venv dans un service systemd

systemd n'est pas un shell interactif : inutile d'exécuter source .venv/bin/activate. Indiquez le chemin absolu de Python dans ExecStart et conservez les secrets dans un fichier aux permissions restreintes, séparé du code source.

# /etc/systemd/system/sample-app.service
[Unit]
Description=Sample Python application
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sampleapp
Group=sampleapp
WorkingDirectory=/opt/sample-app
EnvironmentFile=/etc/sample-app/sample-app.env
ExecStart=/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemd-analyze verify /etc/systemd/system/sample-app.service
sudo systemctl daemon-reload
sudo systemctl enable --now sample-app.service
sudo systemctl status sample-app.service --no-pager
sudo journalctl -u sample-app.service -n 100 --no-pager

Pourquoi recréer un venv plutôt que le déplacer

Le shebang d'un script installé peut contenir le chemin absolu de l'interpréteur de l'environnement. Copier le répertoire ailleurs ou sur un autre serveur peut invalider ce chemin : ne considérez donc pas le venv comme un artefact de déploiement. La méthode officiellement recommandée consiste à créer l'environnement à sa destination et à réinstaller les paquets depuis les fichiers de dépendances ou un wheelhouse.

# Consigner les conditions d'exécution et les dépendances de l'environnement existant
.venv/bin/python --version
.venv/bin/python -m pip freeze > requirements.txt

# Recréer l'environnement au nouvel emplacement
python3 -m venv /opt/sample-app/.venv
/opt/sample-app/.venv/bin/python -m pip install -r requirements.txt
/opt/sample-app/.venv/bin/python -m pip check

Supprimer un venv en sécurité

Supprimer un environnement virtuel revient à effacer son répertoire, mais une variable erronée ou un chemin vide peut supprimer d'autres données. Vérifiez d'abord le chemin absolu et pyvenv.cfg, puis assurez-vous qu'aucun service actif n'utilise l'environnement.

# Ce bloc s'exécute dans un sous-shell ; son annulation ne ferme pas le shell de connexion.
(
  set -eu
  VENV="$(realpath -e -- .venv)"
  test -d "$VENV" && test -f "$VENV/pyvenv.cfg" || {
    echo '가상환경 디렉터리가 아니므로 중단합니다.' >&2
    exit 1
  }
  case "$VENV" in /|"$HOME"|/opt|/usr|/var)
    echo '삭제할 수 없는 상위 경로입니다.' >&2; exit 1 ;;
  esac
  printf 'delete target: %s\n' "$VENV"
  grep -R --fixed-strings "$VENV" /etc/systemd/system /etc/cron* 2>/dev/null || true
  # Examiner les chemins ci-dessus et les services ou tâches cron actifs avant de répondre.
  read -r -p '이 경로만 삭제하려면 DELETE 입력: ' answer
  if [ "$answer" != DELETE ]; then
    echo '취소했습니다.'
    exit 0
  fi
  rm -rf -- "$VENV"
)

Problèmes fréquents et corrections

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
python -m pip list
python -m pip check
python -m site

Choisir entre venv, virtualenv, pipx et conda

• venv : adapté à la gestion manuelle des environnements de projets avec la seule bibliothèque standard Python.
• virtualenv : à envisager pour davantage d'options de création ou des fonctions de compatibilité Python plus étendues.
• pipx : adapté à l'installation d'outils CLI Python comme Black ou Ansible Lint dans leurs propres environnements, avec des commandes accessibles globalement.
• conda : courant dans les environnements scientifiques et de données qui doivent gérer des bibliothèques natives en plus des paquets Python.

Pour les projets serveur et de développement courants, commencer par Python venv simplifie l'isolation des dépendances. Choisissez un autre outil lorsqu'un besoin précis le justifie, comme distribuer des outils CLI ou gérer des dépendances natives.

Points à vérifier en pratique

1. Vérifier l'exécutable Python souhaité et sa version avant la création.
2. Installer les paquets avec python -m pip et les valider avec pip check.
3. Exclure .venv/ du contrôle de version et conserver les fichiers requirements ou de verrouillage.
4. Exécuter les services de production avec le chemin absolu de Python plutôt qu'un script d'activation.
5. Recréer les environnements à destination au lieu de les copier ou de les déplacer.
6. Préparer les ensembles hors ligne avec le même système, CPU et Python, puis vérifier les sommes SHA-256.
7. Avant suppression, vérifier le chemin résolu, pyvenv.cfg et les références des services ou tâches cron.

Guides associés

• Préparer NetBox avec Podman pour un réseau isolé
• Ansible en pratique et exemples

Références officielles

• Documentation officielle Python venv
• PyPA : installer des paquets avec pip et les environnements virtuels
• pip : installations reproductibles
• PyPA : installer des outils CLI autonomes avec pipx

Conclusion

L'essentiel de Python venv n'est pas la commande d'activation, mais la séparation des chemins de l'interpréteur et des paquets du projet, ainsi que la reproductibilité de l'environnement. Activez .venv par commodité en développement et utilisez des chemins absolus pour l'automatisation en production. Gérer ensemble les dépendances, les conditions d'exécution, l'intégrité et le remplacement rend venv fiable sur les serveurs connectés comme isolés.