A Python site runs your own Python web app: Django, Flask, FastAPI, Starlette, or anything else that serves HTTP on a port. We install its dependencies into a virtual environment of its own, start it as a supervised service and put nginx in front. This article covers what your app must do, and what we do for it.
How it runs
- Python 3.12, 3.13, 3.14 and 3.15, switchable on the site page under Configure → Python version: pick a version under Run on and press Switch. Each version always runs its newest release (the list shows it exactly, such as Python 3.14.10); when a newer patch comes out, your app restarts on it the same night.
- Every version has its own virtual environment, and it is kept. Switching installs your dependencies into the new version's environment first and only then restarts your app on it, usually within a couple of minutes; your site keeps answering on the old version until then. If the install fails, your app stays on the version it had. Switching back to a version you used before is quick: its environment is still there.
- Your app is started by the system service manager as its own user, restarted if it crashes, and given a memory limit that fits your plan.
- nginx listens on the outside. Anything in your project's
public/folder is served straight from disk; every other request is proxied to your app. - TLS, your domain, backups and monitoring work as for every other site.
Dependencies
On every deploy, every version switch and every start we check your dependencies and install them with pip into the site's virtual environment when they have changed (an unchanged list is not reinstalled, so restarts stay fast):
uv.lock(with itspyproject.toml) in your project root: uv installs exactly the locked set (uv sync --frozen --no-dev): development dependencies are left out, and nothing is upgraded behind your back. Your project itself is installed too when itspyproject.tomldeclares a build system;- otherwise
requirements.txt:pip install -r requirements.txt; - otherwise
pyproject.toml: the packages listed under[project]dependencies. Your project itself is not built as a package, so an app that is just a folder of modules works too.
Pin your versions (a committed uv.lock, or Django==5.2.* in requirements.txt) so a deploy installs what you tested. A uv.lock that no longer matches pyproject.toml fails the deploy: run uv lock and push again. Packages with compiled parts install from wheels; if one has no wheel for your Python version yet, switch to the version before it.
Deploying
Connect a repository on the site's Deploys tab under Deploy from Git (see Deploy from Git). On every deploy we copy your project into your site, install its dependencies as above, restart your app and wait for it to answer on its port. A broken start command or a missing dependency fails the deploy, and the deploy log says why. Install & restart on the Deploys tab runs the same install and restart on the code already on your site.
Django migrations run for you. When your project has a manage.py, every deploy runs python manage.py migrate --noinput with your site's environment variables, after the new dependencies are installed and before your app restarts on the new code. We back up the site database first (the last five copies are kept). A failed migration stops the deploy, your app keeps running as it was, and the deploy log shows the error. The database migrations switch under Build steps on the Deploys tab turns this off. With release approval on, migrations wait for the approval with the release. Other frameworks: run yours from the start command (alembic upgrade head && uvicorn main:app --host 127.0.0.1 --port $PORT) or over SSH.
The start command
Leave Start command empty and we work it out from your project, in this order:
- a
Procfilewith aweb:line; - Django:
manage.pyplus a<project>/wsgi.py, with gunicorn installed —gunicorn <project>.wsgi; - FastAPI:
main.pythat createsFastAPI(...), with uvicorn installed —uvicorn main:app; - Flask:
app.pythat createsFlask(...), with gunicorn installed —gunicorn app:app; python main.pyorpython app.py;- otherwise a placeholder page, until you deploy.
When your app needs something else, set it on the site page under Configure → Python version → Start command and press Save. Leave it empty to go back to detection.
| Framework | Add to your dependencies | Start command |
|---|---|---|
| Django | gunicorn |
gunicorn mysite.wsgi --bind 127.0.0.1:$PORT |
| Flask | gunicorn |
gunicorn app:app --bind 127.0.0.1:$PORT |
| FastAPI | uvicorn |
uvicorn main:app --host 127.0.0.1 --port $PORT |
| Anything else | python main.py (reading PORT itself) |
The command runs from your project root with your site's virtual environment first on the PATH, so python, gunicorn and uvicorn are the ones you installed. Quotes are not allowed in it.
The PORT environment variable
Your app must listen on the port in the PORT environment variable, on 127.0.0.1: nginx connects to it locally. gunicorn and uvicorn take it as shown above; in plain Python read os.environ["PORT"]. We also set PYTHONUNBUFFERED=1, so what your app prints reaches the logs straight away.
Add your own variables (secret keys, API keys) under Configure → Environment variables; your app is restarted so it picks them up. PORT is always ours. If your site has a managed database, its DB_* variables are set for you: read them with os.environ["DB_HOST"] and friends.
Behind a proxy
Requests reach your app over plain HTTP from nginx, with the real details in headers: X-Forwarded-Proto (https), X-Forwarded-For and X-Forwarded-Host. Tell your framework to trust them, so it builds https:// links: in Django, SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https") and your domain in ALLOWED_HOSTS; in Flask, werkzeug's ProxyFix; with uvicorn, --proxy-headers.
When something breaks
The Logs tab shows your app's own output, so a failed start is easy to spot. Common causes: the app listens on a fixed port instead of PORT, gunicorn or uvicorn is missing from your dependencies, or a package has no build for the Python version you switched to. Fix, push, deploy again.