PYTHON-MODULE(5)

📦 in nixpkgs unstable

💖 NAME 💖

okay so welcome to PYTHON-MODULE(5) from the File Formats Manual — this is the manual for python-module, aka the lang/python port module. It’s giving “bestie, let’s package Python ports correctly” and honestly? iconic. 💅

🦋 DESCRIPTION 🦋

This manual page documents the behavior of setting MODULES=lang/python in the ports(7) tree. That’s the vibe check. 🫶

By default, the module builds ports using Python 3. For legacy ports using Python 2, MODPY_VERSION may be set manually to ${MODPY_DEFAULT_VERSION_2}. Legacy means legacy, but we still document it, no erasure.

The module then sets these beauties accordingly: MODPY_BIN, MODPY_INCDIR, MODPY_LIBDIR, MODPY_SITEPKG, MODPY_SETUP, MODPY_TEST_DIR, MODPY_TEST_LOCALE, MODPY_WANTLIB, MODPY_LIB_DEPENDS, MODPY_RUN_DEPENDS, MODPY_TEST_DEPENDS, MODPY_BUILD_DEPENDS, and MODPY_ADJ_FILES. Yes, all of them. The whole squad. 💖

The module also adds a dependency on the Python interpreter to:

  • RUN_DEPENDS unless MODPY_RUNDEP is set to No,
  • BUILD_DEPENDS unless MODPY_BUILDDEP is set to No or NO_BUILD is set to Yes,
  • TEST_DEPENDS if MODPY_PYTEST is set to Yes unless MODPY_TESTDEP is set to No.

It also appends MODPY_TEST_LOCALE to TEST_ENV and changes to the directory specified in MODPY_TEST_DIR (by default ${WRKSRC}) before running tests. So yes, it’s moving the group chat to the right folder first. 🚶‍♀️

Most modern Python software can be packaged using a PEP 517 build frontend (in the devel/py-build port). To use this, set MODPY_PYBUILD to the name of the build backend. If the port provides a pyproject.toml file, check the "build-backend" line in the [build-system] section. If no pyproject.toml is provided then it most likely uses setuptools. Checks for some common MODPY_PYBUILD misconfigurations are performed during build and, if found, warnings are displayed after fake-install. Not me getting feedback after fake-install 😭 but it’s useful.

python-module currently supports flit, flit_core, flit_scm, hatch-vcs, hatchling, jupyter_packaging, maturin, mesonpy, pbr, pdm, poetry-core, poetry-dynamic-versioning, scikit-build-core, setuptools, setuptools-rust, setuptools_scm, and uv_build. In cases where an uncommon backend is used, or where the build backend is distributed with the software itself, MODPY_PYBUILD can be set to other to use the PEP 517 build mechanism without adding a dependency for a backend.

Setting MODPY_PYBUILD adds the backend to MODPY_BUILD_DEPENDS, and sets MODPY_PYTEST. The build is run in MODPY_BUILD_DIR, defaulting to WRKSRC.

If using the maturin backend, it is usually necessary to set MODCARGO_CARGOTOML to the file specified by manifest-path in pyproject.toml.

Python 2 ports using setuptools set MODPY_SETUPTOOLS to Yes, which appends to MODPY_BUILD_DEPENDS and calls the relevant commands to build (these ports are built using the deprecated mechanism of calling setup.py directly). Arguments can be passed to setup.py during configure with MODPY_SETUP_ARGS. Extra arguments to the build and install commands can be passed via MODPY_DISTUTILS_BUILDARGS and MODPY_DISTUTILS_INSTALLARGS.

⚠️ bestie, hear me: MODPY_SETUPTOOLS should not be used for new ports. It’s the deprecated setup.py route. Cute for legacy, not for your new main character port. 💀

Ports using pytest should set MODPY_PYTEST to Yes unless MODPY_PYBUILD is used, in which case it is already set by default. Arguments can be passed to pytest during test with MODPY_PYTEST_ARGS, for example to list names of test scripts if the automatic detection fails, to disable certain test scripts with --ignore, or to disable certain individual tests with -k. A user setting MODPY_PYTEST_USERARGS, if present, is passed on the command line. This allows setting pytest flags to increase verbosity, show test durations, enable colours, etc. slay for verbose test output 🌈

If MODPY_TEST_LINK_SO is set to Yes, symbolic links to all .so files in the build directory will be created before running tests. These are created in MODPY_TEST_LINK_SRC, which defaults to ${WRKSRC}. This is required when tests load .so files via relative imports.

All ports that generate egg-info or dist-info files should set MODPY_DISTV to the version string used by the setup() function in the port's setup.py or the version in pyproject.toml.

If any files have a python shebang line where the interpreter should be ${MODPY_BIN}, list them in MODPY_ADJ_FILES. These filenames can be relative to ${WRKSRC} and will be modified at the end of pre-configure.

For ports not using standard Python build infrastructure, it may be necessary to bytecode-compile installed .py files. This can be done by using ${MODPY_COMPILEALL}, usually in a post-install target. This passes flags to use MAKE_JOBS, strip off WRKINST, and use standard optimization passes. File or directory names can be given. Directories are handled recursively.

This module also affects CATEGORIES, MAKE_ENV, CONFIGURE_ENV, and SUBST_VARS, and it may affect the test target.

If MODPY_PI is set to Yes, the module will provide a default for HOMEPAGE and set SITES (the subdirectory can be overridden with MODPY_PI_DIR).

🌈 SEE ALSO 🌈

mwah 💋 this page is served fresh from Debian, dated March 22, 2026, and it’s PYTHON-MODULE(5) signing off. stay slay, package responsibly 🫶✨

📦 where this page comes from