Docs menu
Customizing the build
How to shape the Python build on Primcloud: release-phase commands, custom install steps, native dependencies, and Debian packages via project.toml.
On this page
Most Python apps deploy on Primcloud with no custom build steps. The build installs Python, resolves dependencies with the package manager it picked, and (for Django) runs collectstatic. When you need more, the extension points are release-phase commands in the Procfile, native-dependency handling that piggybacks on your package manager, and Debian package installs for OS-level libraries.
Build hooks#
The Python build does not read bin/pre_compile / bin/post_compile scripts. Those are a Heroku Classic convention that Primcloud doesn't carry forward. Two places to hang work off a deploy instead:
Release phase. Anything that has to run once per deploy, like database migrations, goes in the release process in your Procfile. It runs after the build and before the new version takes traffic; if it exits non-zero, the deploy stops and your running app is unchanged.
web: gunicorn myapp.wsgi
release: python manage.py migrate --noinput
Django's collectstatic. Runs automatically at the end of the build when Django is installed and manage.py is at the root, with no configuration needed. See Python on Primcloud → Release phase conventions.
Build backend hooks. If you need code to run during dependency install itself, hang it off your package's own build backend. Any package installed from a source distribution runs its pyproject.toml-declared build backend (setuptools, hatchling, poetry-core, uv-build, and so on), and those backends run whatever build steps they're told to. This fires during pip install, poetry sync, or uv sync when the package is installed from source rather than a pre-built wheel.
Custom install steps#
You don't configure the install command directly. The build picks one command per package manager and runs it. To shape what gets installed:
- pip. Everything is driven by
requirements.txt. Pin exact versions, include--extra-index-urllines, use environment variable interpolation for tokens, add-e path/to/local-packagefor editable installs of packages in your repo. - Poetry.
pyproject.tomlandpoetry.lockdrive it. Dependency groups keep dev and test tools out of your deployed app: the build only installs--only main, so anything in[tool.poetry.group.dev.dependencies](or any other non-main group) is skipped automatically. - uv.
pyproject.tomlanduv.lockdrive it. Similarly,[dependency-groups.dev]and other non-default groups are skipped: the build runs with--no-default-groups, so only the main dependency table is installed.
The build does not read .buildpacks or buildpack.yml files.
Native dependencies#
There are two shapes of "native" your Python app can rely on:
Compiled Python packages. Packages that ship as pre-built wheels (numpy, pandas, cryptography, pydantic-core, and most of the popular ones) install without needing to compile anything. The right wheel for your Python version is downloaded and unpacked. This is the common case.
Packages that build from source. When a package only ships an sdist (or a wheel isn't available for the target Python version / architecture), pip / Poetry / uv compile it from source during the install. The build has a C toolchain and headers for the Python interpreter, so most C-extension packages build without extra setup.
Packages that depend on OS-level shared libraries (libpq for psycopg2-binary's sibling psycopg2, libxml2/libxslt for lxml built from source, libmagic for python-magic, and so on) need those libraries installed at both build and runtime. Declare them in project.toml, covered in the next section.
Tip
Binary wheels. Where a package publishes both a source distribution and pre-built wheels (like psycopg2-binary versus psycopg2, or mysqlclient versus mysql-connector-python), the binary-wheel variant almost always avoids the OS-library-and-toolchain requirement. Prefer it unless you have a specific reason not to.
Debian packages#
When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:
[_]
schema-version = "0.2"
[com.heroku.buildpacks.deb-packages]
install = [
"libpq-dev",
"libxml2",
"libxslt1.1",
"libmagic1",
]
Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.
Advanced options (rarely needed):
- Skip a package's dependencies:
{ name = "some-package", skip_dependencies = true } - Force a reinstall:
{ name = "some-package", force = true } - Install from a URL:
download = ["https://example.com/package-1.2.3.deb"] - Add a package repository: a
[[com.heroku.buildpacks.deb-packages.sources]]table withuri,suites,components,arch, andsigned_by(the repository's key as an ASCII-armored PGP block).
Note
The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.