Docs menu
Python on Primcloud
How Primcloud detects a Python app, installs Python and your dependencies, and runs Django's collectstatic.
On this page
Detection#
Primcloud builds your app as Python when the root of your repo has any of:
.python-versionrequirements.txtpoetry.lockuv.lockpyproject.tomlPipfileorPipfile.lockpdm.lockruntime.txtsetup.py,setup.cfg,manage.py,app.py,main.py,server.py, or__init__.py- A
__pycache__/or.venv/directory
If something's missing, the build fails with an error saying what. The file at the root decides the package manager:
requirements.txt→ pippoetry.lock→ Poetryuv.lock→ uv
Exactly one of them must be at the root; with more than one, or none, the build fails. Pipenv isn't supported; see Package managers.
Python takes precedence. A repo with both a Python file and, say, a package.json builds as Python. To build it as something else, keep Python files out of the root.
The build#
- Python. The build installs the version in
.python-version, or the newest Python 3.14 if there's none. uv apps must have a.python-version. See Runtime versions. - Package manager. pip, Poetry, or uv is installed at a version that's part of the Primcloud Runtime.
- Dependencies. They're installed into a virtual environment, which is active at runtime:
- pip:
pip install --no-input --progress-bar off --requirement requirements.txt - Poetry:
poetry sync --only main --compile --no-interaction - uv:
uv sync --locked --no-default-groups --compile-bytecode --no-progress
- pip:
All three compile .pyc files during the install, so your app starts faster. Native extensions compile during the install too; see Customizing the build.
Python, your package manager, and your downloads are reused from the previous build when they haven't changed. With Poetry and uv, so is the virtual environment, which they keep matched to your lockfile; with pip it's installed fresh each build. The build log says when it reuses Python (Using cached Python 3.14.6) or replaces it.
Processes#
A Procfile is required. Python apps get no default web process; see Formations. A typical Django app's:
web: gunicorn myapp.wsgi
worker: celery -A myapp worker --loglevel=info
release: python manage.py migrate --noinput
Your web process must listen on $PORT, and a deploy doesn't go live until it does. Read the value from the environment; don't hard-code a number.
Django collectstatic. If Django is installed in the venv and the repo has a manage.py at the root, the build runs python manage.py collectstatic --noinput at the end of the build. Skipped automatically when:
- No
manage.pyis at the repo root. - Django is installed but
django.contrib.staticfilesisn't enabled in the app's settings.
If collectstatic runs and fails, the build fails. Django surfaces the error, most often a settings misconfiguration or a missing dependency needed to import the settings module.
Environment. Every process gets these, plus your secrets:
| Variable | Value | Purpose |
|---|---|---|
PATH |
With the venv's bin/ first, then Python's bin/ |
So python, pip, gunicorn, and any installed console scripts resolve. |
VIRTUAL_ENV |
Path to the app's virtual environment | As source bin/activate would set it, so tools like pip use it. |
PYTHONUNBUFFERED |
1 |
Disables Python's output buffering so logs aren't lost when a process crashes. |
PORT |
Set by Primcloud | Present on web process types only; non-web processes get no PORT. |
A few secrets would break the build, such as VIRTUAL_ENV, PYTHONHOME, PIP_TARGET, POETRY_HOME, and UV_PROJECT_ENVIRONMENT, and setting one fails the build. See Troubleshooting Python → Unsafe environment variable for the list.