pybuild(1)

📦

version 7.20260623ubuntu2 · 6 versions

7.20260623ubuntu2 · ubuntu stonking (latest)
5.20220403 · ubuntu jammy
5.20230130 · debian bookworm
6.20240401 · ubuntu noble
7.20260309 · ubuntu resolute
6.20250414 · debian trixie, ubuntu questing

💅 `pybuild`(1) — General Commands Manual 🐍✨

okay so you found the pybuild page, bestie, and let me tell you, this one is a journey. Grab a boba, sit down, and let's get into it.

🎀 NAME

pybuild — invokes various build systems for requested Python versions in order to build modules and extensions

like... that's the whole vibe. it rounds up your Python versions like a group-chat organizer and gets your modules and extensions built. no cap. 🫶

✨ SYNOPSIS

pybuild [ACTION] [BUILD SYSTEM ARGUMENTS] [DIRECTORIES] [OPTIONS]

that's the shape of it, bestie: an action, then build-system arguments, then directories, then options. iconic lineup honestly. 💅

🦋 DEBHELPER COMMAND SEQUENCER INTEGRATION

this is the part where pybuild gets adopted into your debian/rules and starts pulling its weight. here's the checklist, in order:

build depend on dh-python,
build depend on all supported Python interpreters — pybuild will use it to create a list of interpreters to build for. the ones it knows and loves (recognized dependencies):
- python3-all-dev — for Python extensions that work with Python 3.X interpreters,
- python3-all-dbg — as above, add this one if you're building -dbg packages,
- python3-all — for Python modules that work with Python 3.X interpreters,
- python3-dev — builds an extension for default Python 3.X interpreter (useful for private extensions, use python3-all-dev for public ones),
- python3 — as above, used if headers files are not needed to build private module,
add --buildsystem=pybuild to dh's arguments in debian/rules,
if more than one binary package is build: add debian/python3-foo.install files, or export PYBUILD_NAME=modulename (modulename will be used to guess binary package prefixes), or export PYBUILD_DESTDIR env. variables in debian/rules
add --with=python3 to dh's arguments in debian/rules (see proper helper's manpage for more details) or add dh-sequence-python3 to Build-Depends

and now the moment you've all been waiting for: the debian/rules file example. screenshot it, tattoo it, put it on your moodboard, whatever works bestie 💖

#! /usr/bin/make -f
export PYBUILD_NAME=foo
%:
       dh $@ --with python3 --buildsystem=pybuild

lowkey the cleanest little rules file you'll ever see. it's giving main character energy. ✨

✨ OPTIONS ✨

okay so bestie, most of these options can be set via command line OR via environment variables, you get both. PyBuild goes looking in this order:

PYBUILD_OPTION_VERSIONED_INTERPRETER (f.e. PYBUILD_CLEAN_ARGS_python3.2)
PYBUILD_OPTION_INTERPRETER (f.e. PYBUILD_CONFIGURE_ARGS_python3-dbg)
PYBUILD_OPTION (f.e. PYBUILD_INSTALL_ARGS)

🎀 optional arguments 🎀

-h, --help — show this help message and exit 💖
-v, --verbose — turn verbose mode on (she's chatty now)
-q, --quiet — doesn't show external command's output
-qq, --really-quiet — be quiet. like, actually
--version — show program's version number and exit

🫡 ACTION

Default vibe? Build, install and test the library using the detected build system, version by version. But if you pick one of the following actions, it invokes that action for all versions — one by one — which (unlike the default) in some build systems can overwrite previous results. so heads up 👀

--detect — return the name of detected build system
--clean — clean files using auto-detected build system specific methods
--configure — invoke configure step for all requested Python versions
--build — invoke build step for all requested Python versions
--install — invoke install step for all requested Python versions
--test — invoke tests for auto-detected build system
--list-systems — list available build systems and exit
--print — print pybuild's internal parameters

🧪 TESTS

By default the test step uses unittest's discover from the standard library. But if no tests are found, that's ignored (she's forgiving). Want tests to be required? Use --test-unittest. 💅

--test-nose — use nose module in test step, remember to add python3-nose to Build-Depends.
--test-nose2 — use nose2 module in test step, remember to add python3-nose2 to Build-Depends.
--test-pytest — use pytest module in test step, remember to add python3-pytest to Build-Depends.
--test-tox — use tox command in test step, remember to add tox to Build-Depends.
--test-stestr — use stestr command in test step, remember to add python3-stestr to Build-Depends.
--test-unittest — use unittest discover in the test step, requiring at least 1 test to be discovered.
--test-custom — use a custom command in the test step. The full test command is then specified with --test-args or by setting the PYBUILD_TEST_ARGS environment variable. Remember to add any needed packages to run the tests to Build-Depends.

📂 testfiles

Tests get invoked from inside the build directory, so the freshly built files get tested instead of the source files. main character behaviour only ✨

If your test suite needs other files chillin' in that directory, list them in debian/pybuild.testfiles (you can also use debian/pybuild_pythonX.testfiles or debian/pybuild_pythonX.Y.testfiles) and the files listed there get copied before the test step and removed before the install step.

By default only pyproject.toml and pytest.ini files, plus the test and tests directories are copied to the build directory. If testfiles are provided, it overrides those defaults — so if you still want them, you gotta spell them out explicitly.

By default, the test files are copied at the root of the build directory. You can optionally specify a destination as a second argument in the testfiles. If the destination ends with a / it is treated as a target directory into which the file will be copied. 🎀

🔧 BUILD SYSTEM ARGUMENTS

Extra arguments passed to the build system. Heads up: --system=custom requires a complete command in the --foo-args parameters. no short cuts bestie.

--before-clean COMMAND — invoked before the clean command
--clean-args ARGUMENTS — arguments added to clean command generated by build system plugin
--after-clean COMMAND — invoked after the clean command
--before-configure COMMAND — invoked before the configure command
--configure-args ARGUMENTS — arguments added to configure command generated by build system plugin
--after-configure COMMAND — invoked after the configure command
--before-build COMMAND — invoked before the build command
--build-args ARGUMENTS — arguments added to build command generated by build system plugin
--after-build COMMAND — invoked after the build command
--before-install COMMAND — invoked before the install command
--install-args ARGUMENTS — arguments added to install command generated by build system plugin
--after-install COMMAND — invoked after the install command
--before-test COMMAND — invoked before the test command
--test-args ARGUMENTS — arguments added to test command generated by build system plugin
--after-test COMMAND — invoked after the test command

🪄 variables that can be used in ARGUMENTS and COMMAND

{version} will be replaced with current Python version, you can also use {version.major}, {version.minor}, etc.
{interpreter} will be replaced with current interpreter, you can also use {interpreter.include_dir}
{dir} will be replaced with sources directory,
{destdir} will be replaced with destination directory,
{home_dir} will be replaced with temporary HOME directory, where plugins can keep their data (.pybuild/interpreter_version/ by default),
{build_dir} will be replaced with build directory
{install_dir} will be replaced with install directory.
{package} will be replaced with suggested package name, if --name (or PYBUILD_NAME) is set to foo, this variable will be replaced with python3-foo.

📁 DIRECTORIES

-d DIR, --dir DIR — set source files directory — base for other relative dirs [by default: current working directory]
--dest-dir DIR — set destination directory [default: debian/tmp]
--ext-dest-dir DIR — set destination directory for .so files
--ext-pattern PATTERN — regular expression for files that should be moved if --ext-dest-dir is set [default: .so(.[^/]*)?$]
--ext-sub-pattern PATTERN — regular expression for part of path/filename matched in --ext-pattern that should be removed or replaced with --ext-sub-repl
--ext-sub-repl PATTERN — replacement for matches in --ext-sub-pattern
--install-dir DIR — set installation directory [default: .../dist-packages]
--name NAME — use this name to guess destination directories (foo changes the default --dest-dir setting debian/python3-foo). This name can also be used to keep multiple builds of unrelated python modules separate from each other. Run pybuild once with --name set to a different value, for each module, at each step of the build. 🔥

🌸 variables that can be used in DIR

{version} will be replaced with current Python version,
{interpreter} will be replaced with selected interpreter.

⚠️ LIMITATIONS

-s SYSTEM, --system SYSTEM — select a build system [default: auto-detection]
-p VERSIONS, --pyver VERSIONS — build for Python VERSIONS. This option can be used multiple times. Versions can be separated by space character. The default is all Python 3.X supported versions.
-i INTERPRETER, --interpreter INTERPRETER — change interpreter [default: python{version}]
--disable ITEMS — disable action, interpreter, version or any mix of them. Note that f.e. python3 and python3-dbg are two different interpreters, --disable test/python3 doesn't disable python3-dbg's tests. (sneaky, ik 😭)
-j NUM, --parallel NUM — specify number of parallel jobs [default: 1]

💀 disable examples

--disable test/python3.9-dbg — disables tests for python3.9-dbg
--disable '3.8 3.9' — disables all actions for version 3.8 and 3.9
PYBUILD_DISABLE=python3.9 — disables all actions for Python 3.9
PYBUILD_DISABLE_python3.3=test — disables tests for Python 3.3
PYBUILD_DISABLE=test/python3.3 — same as above
PYBUILD_DISABLE=configure/python3 3.2 — disables configure action for all python3 interpreters, and all actions for version 3.2

👑 PLUGINS

pybuild supports multiple build system plugins. By default it is automatically selected. These systems are currently supported:

distutils (most commonly used)
cmake
flit (deprecated)
pyproject
custom

flit plugin

The flit plugin is deprecated, please use the pyproject plugin instead. (she's retired, respect her legacy 💜)

The flit plugin can be used to build Debian packages based on PEP 517 metadata in pyproject.toml when flit is the upstream build system. These can be identified by the presence of a build-backend = "flit_core.buildapi" element in pyproject.toml. The flit plugin only supports python3. To use this plugin:

build depend on flit, and
add export PYBUILD_SYSTEM=flit to debian/rules to manually select

debian/rules file example:

#! /usr/bin/make -f
export PYBUILD_NAME=foo
export PYBUILD_SYSTEM=flit
%:
    dh $@ --with python3 --buildsystem=pybuild

pyproject

The pyproject plugin drives the new PEP-517 standard interface for building Python packages, upstream. This is configured via pyproject.toml. This plugin is expected to replace the distutils and flit plugins in the future. ✨

The entry points generated by the package are created during the build step (other plugins make the entry points during the install step); the entry points are available in PATH during the test step, permitting them to be called from tests. no cap, that part's important 🫶

To use this plugin:

build depend on pybuild-plugin-pyproject as well as any build tools specified by upstream in pyproject.toml.

🌸 ENVIRONMENT 🌸

okay bestie so here's the tea: like we said up in OPTIONS, pybuild takes its settings from environment variables that are all prefixed with PYBUILD_. that's the whole vibe. set the var, get the behaviour, no cap 💅

Tests get skipped if nocheck shows up in either the DEB_BUILD_OPTIONS or the DEB_BUILD_PROFILES environment variables. like, if you said nocheck, you meant nocheck, and pybuild respects that fr fr ✨

DESTDIR provides a default a default value to the --dest-dir option. (yes, the original manpage says "default a default" twice, and honestly? iconic typo energy, we're keeping it exactly as it is 🎀)

Oh also, the network thing, and this one is lowkey important: pybuild will export

http_proxy=http://127.0.0.1:9/

https_proxy=https://127.0.0.1:9/

no_proxy=localhost

to hopefully block attempts by the package's build-system to access the Internet. like, go to your room, build system, no internet for you 🚪💀

but heads up bestie: if network access to a loopback interface is needed and it's blocked by this, export empty http_proxy and https_proxy variables before calling pybuild. that's the fix, that's the move 🫶

and if they're not set, then LC_ALL, CCACHE_DIR, DEB_PYTHON_INSTALL_LAYOUT, _PYTHON_HOST_PLATFORM, and _PYTHON_SYSCONFIGDATA_NAME will all be set to appropriate values before calling the package's build script. pybuild just handles it for you, main character behaviour honestly 👑

🦋 SEE ALSO 🦋

dh_python3(1)
<https://wiki.debian.org/Python/Pybuild>
<http://deb.li/pybuild> — most recent version of this document

💜 Author 💜

Piotr Ożarowski, 2012-2019

okay periodt, that's the whole pybuild(1) manual page, start to finish, and you ate every single bit of it 🌈⭐ go build something gorgeous, bestie — and remember, the tests only get skipped if you say nocheck 💖🎀🦋

pybuild(1) — that's the source and version tag, and the date lives right there in the footer too. love you, bye 👋✨

📦 where this page comes from

ubuntu stonking: dh-python 7.20260623ubuntu2 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms