Python 3 and virtual environments

Python 3 is included by default on Ubuntu/Debian images for HolyCloud Linux VPS instances. Virtual environments (venv) isolate each project's dependencies and avoid conflicts with system packages.

Prerequisites

• HolyCloud VPS Ubuntu 22.04/24.04 or Debian 12
• sudo access or a user with write access in their home directory
• SSH connection

Step 1: Check Python 3

python3 --version
which python3

Install base tools if missing:

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

Update pip for the current user:

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

Step 2: Create a virtual environment

Choose a project directory:

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

Created structure:

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

Step 3: Activate and use the venv

Activation (bash):

source .venv/bin/activate

The prompt shows (.venv). Verify:

which python
which pip
python --version

Install packages in the venv:

pip install fastapi uvicorn requests
pip freeze > requirements.txt

Deactivate:

deactivate

Step 4: Run an application (FastAPI example)

main.py file:

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

Local test on the VPS:

curl http://127.0.0.1:8000/

To expose behind Nginx, keep the app on 127.0.0.1 and configure a reverse proxy (see Nginx tutorial).

Step 5: Recreate the environment on another server

Copy the project (without .venv — too large):

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

On the target:

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

Step 6: systemd service (production)

File /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

Best practices on HolyCloud VPS

• Do not install pip packages with sudo pip install on system Python
• Add .venv/ and __pycache__/ to .gitignore
• On small VPS (1 GB RAM), limit Uvicorn/Gunicorn workers

Verification

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

HolyCloud support

• externally-managed-environment (Debian 12): always use a venv, not global apt pip
• Module not found after reboot: check PATH in the systemd service
• HolyCloud support: python3 --version, start command, journalctl -u mon-api logs