Use a Python virtual environment

A virtual environment isolates a project's dependencies from the system. On a VPS you create and activate it yourself. On managed Python hosting, requirements.txt provides reproducibility, with no shell and no activation step.

1. Why isolate dependencies

Two projects may need incompatible versions of the same library. Installing globally with pip creates conflicts and can break distribution-provided tools. A virtual environment holds its own linked interpreter, packages and scripts in a dedicated folder, usually .venv.

On Debian 13, the python3-venv package provides the required module:

sudo apt update
sudo apt install python3-venv

2. Create and activate

cd /var/www/my-app
python3 -m venv .venv
source .venv/bin/activate
python -V
pip install -r requirements.txt

source changes the current session's PATH, so python and pip resolve to .venv. The deactivate command restores the system interpreter. To pin the versions actually installed:

pip freeze > requirements.txt

Add .venv/ to .gitignore. A virtual environment is not portable: its binaries and absolute paths belong to one machine and one OS. Recreate it rather than copying it.

3. On application hosting

NeoHeberg Python hosting provides no shell and no root access. The panel installs dependencies from requirements.txt, then runs the start command, python main.py by default. You cannot rely on source .venv/bin/activate inside that command.

Instead:

• list every direct dependency in requirements.txt;
• pin versions (package==1.2.3) to avoid a surprise upgrade;
• test the install in a local virtual environment before redeploying;
• restart the app and read the console for a ModuleNotFoundError.

Environment variables are set in the panel, not in an uploaded .env file.

4. On a VPS with systemd

Calling the venv interpreter directly avoids activation inside the service:

[Service]
User=app
WorkingDirectory=/var/www/my-app
EnvironmentFile=/etc/my-app.env
ExecStart=/var/www/my-app/.venv/bin/python main.py

After editing: sudo systemctl daemon-reload, then sudo systemctl restart my-app. Check with systemctl status and journalctl -u my-app -n 50.

5. Verify

• which python should point to .venv/bin/python while the environment is active.
• python -c "import sys; print(sys.prefix)" prints the venv folder.
• pip list should contain only project packages and their dependencies.
• On managed hosting, a clean reinstall must succeed without any manual step.

If a package compiles native modules, check that a binary wheel exists for the offered Python version. Otherwise pick a compatible version or avoid that dependency.