PYTHON-MODULE(5) | File Formats Manual | PYTHON-MODULE(5)

# NAME

`python-module` — lang/python port module

# DESCRIPTION

This manual page documents the behavior of setting `MODULES=lang/python` in the ports(7) tree.

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}.

The module then sets `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` accordingly.

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.

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. `python-module` currently supports flit, flit_core, flit_scm, hatchling, hatch-vcs, jupyter_packaging, maturin, mesonpy, pbr, pdm, poetry-core, setuptools, setuptools_scm, setuptools-rust, 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. If no pyproject.toml is provided then it most likely uses setuptools. `python-module` performs some checks and warns about some incorrect `MODPY_PYBUILD` settings after fake-install. Setting `MODPY_PYBUILD` adds the backend to `MODPY_BUILD_DEPENDS`, and sets `MODPY_PYTEST`.

Some checks are done to warn during "make fake" if `MODPY_PYBUILD` appears to be set incorrectly.

Python 2 and some older Python 3 ports using setuptools still 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`. These ports can often be converted to `MODPY_PYBUILD` with some small changes to the port. `MODPY_SETUPTOOLS` should not be used for new ports.

Ports using pytest should set `MODPY_PYTEST` to Yes unless `MODPY_PYBUILD` is used, when 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’. 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.

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

port-modules(5)

September 17, 2025 | Debian