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-version
  • requirements.txt
  • poetry.lock
  • uv.lock
  • pyproject.toml
  • Pipfile or Pipfile.lock
  • pdm.lock
  • runtime.txt
  • setup.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 → pip
  • poetry.lock → Poetry
  • uv.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#

  1. 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.
  2. Package manager. pip, Poetry, or uv is installed at a version that's part of the Primcloud Runtime.
  3. 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

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:

Procfile
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.py is at the repo root.
  • Django is installed but django.contrib.staticfiles isn'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.