Python 3 et environnements virtuels

Python 3 est présent par défaut sur les images Ubuntu/Debian des VPS Linux HolyCloud. Les environnements virtuels (venv) isolent les dépendances de chaque projet et évitent les conflits avec les paquets système.

Prérequis

• VPS HolyCloud Ubuntu 22.04/24.04 ou Debian 12
• Accès sudo ou utilisateur avec droits d'écriture dans son répertoire home
• Connexion SSH

Étape 1 : vérifier Python 3

python3 --version
which python3

Installez les outils de base si manquants :

sudo apt update
sudo apt install -y python3 python3-pip python3-venv python3-dev

Mettez à jour pip dans l'utilisateur courant :

python3 -m pip install --user --upgrade pip

Étape 2 : créer un environnement virtuel

Choisissez un répertoire de projet :

mkdir -p ~/projets/mon-api
cd ~/projets/mon-api
python3 -m venv .venv

Structure créée :

.venv/
  bin/activate
  bin/python
  bin/pip
  lib/...

Étape 3 : activer et utiliser le venv

Activation (bash) :

source .venv/bin/activate

Le prompt affiche (.venv). Vérifiez :

which python
which pip
python --version

Installez des paquets dans le venv :

pip install fastapi uvicorn requests
pip freeze > requirements.txt

Désactivation :

deactivate

Étape 4 : lancer une application (exemple FastAPI)

Fichier main.py :

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"status": "ok", "host": "vps-holycloud"}

source .venv/bin/activate
uvicorn main:app --host 127.0.0.1 --port 8000

Test local sur le VPS :

curl http://127.0.0.1:8000/

Pour exposer derrière Nginx, gardez l'app sur 127.0.0.1 et configurez un reverse proxy (voir tutoriel Nginx).

Étape 5 : recréer l'environnement sur un autre serveur

Copiez le projet (sans .venv — trop volumineux) :

rsync -avz --exclude .venv ~/projets/mon-api/ user@IP_AUTRE_VPS:/home/user/mon-api/

Sur la cible :

cd ~/mon-api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Étape 6 : service systemd (production)

Fichier /etc/systemd/system/mon-api.service :

[Unit]
Description=API Python HolyCloud
After=network.target

[Service]
User=deploy
Group=deploy
WorkingDirectory=/home/deploy/projets/mon-api
Environment="PATH=/home/deploy/projets/mon-api/.venv/bin"
ExecStart=/home/deploy/projets/mon-api/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mon-api
sudo systemctl status mon-api

Bonnes pratiques sur VPS HolyCloud

• Ne pas installer de paquets pip en sudo pip install sur le Python système
• Ajoutez .venv/ et __pycache__/ au .gitignore
• Sur petit VPS (1 Go RAM), limitez les workers Uvicorn/Gunicorn

Vérification

python3 -m venv /tmp/test-venv && source /tmp/test-venv/bin/activate && pip list && deactivate
rm -rf /tmp/test-venv
systemctl status mon-api 2>/dev/null || true

Besoin d'aide HolyCloud

• externally-managed-environment (Debian 12) : utilisez toujours un venv, pas apt pip global
• Module introuvable après reboot : vérifiez le PATH dans le service systemd
• Support HolyCloud : version python3 --version, commande de démarrage, logs journalctl -u mon-api