py-build-cmake configuration options

These options go in the [tool.py-build-cmake] section of the pyproject.toml configuration file.

module

Defines the import name of the module or package, and the directory where it can be found.

Option	Description	Type	Default
`name`	Import name in Python (can be different from the name on PyPI, which is defined in the [project] section).	string	`/pyproject.toml/project/name`
`directory`	Directory containing the Python module/package. Relative to project directory.	path	`'.'`
`namespace`	Set to true for PEP 420 namespace packages.	bool	`false`
`generated`	Do not try to locate the main module in the source directory, but assume that it is generated by CMake. Dynamic metadata cannot be used when set.	`'module'` \| `'package'`	`none`

editable

Defines how to perform an editable install (PEP 660). See https://tttapa.github.io/py-build-cmake/Editable-install.html for more information.

Option	Description	Type	Default
`mode`	Mechanism to use for editable installations. Either write a wrapper __init__.py file, install an import hook, or install symlinks to the original files.	`'wrapper'` \| `'hook'` \| `'symlink'`	`'symlink'`
`build_hook`	Automatically re-build any changed files and C extension modules when the package is first imported by Python. It is recommended to use a fast generator like Ninja. Currently, the only mode that supports build hooks is `symlink`.	bool	`false`

sdist

Specifies the files that should be included in the source distribution for this package.

Option	Description	Type	Default
`include`	Files and folders to include in the source distribution. May include the '' wildcard or '*' for recursive patterns.	list	`[]`
`exclude`	Files and folders to exclude from the source distribution. May include the '' wildcard or '*' for recursive patterns.	list	`[]`

cmake

Defines how to build the project to package. If omitted, py-build-cmake will produce a pure Python package.

Option	Description	Type	Default
`minimum_version`	Minimum required CMake version. Used for policies in the automatically generated CMake cache pre-load files. If this version is not available in the system PATH, it will be installed automatically as a build dependency (using Pip). For example: `minimum_version = "3.18"`	string	`'3.15'`
`build_type`	Build type passed to the configuration step, as `-DCMAKE_BUILD_TYPE=<?>`. For example: `build_type = "RelWithDebInfo"`	string	`none`
`config`	Configuration type passed to the build step, as `--config <?>`. You can specify either a single string, or a list of strings. If a multi-config generator is used, all configurations in this list will be built. For example: `config = ["Debug", "Release"]`	list	`build_type`
`preset`	CMake preset to use for configuration. Passed as `--preset <?>` during the configuration phase.	string	`none`
`build_presets`	CMake presets to use for building. Passed as `--preset <?>` during the build phase, once for each preset.	list	`none`
`generator`	CMake generator to use, passed to the configuration step, as `-G <?>`. If Ninja is used, and if it is not available in the system PATH, it will be installed automatically as a build dependency. For example: `generator = "Ninja Multi-Config"`	string	`none`
`source_path`	Folder containing CMakeLists.txt. Relative to project directory.	path	`'.'`
`build_path`	CMake build and cache folder. The placeholder `{build_config}` can be used to insert the name of the Python version and ABI, operating system, and architecture. This ensures that separate build directories are used for different host systems and Python versions/implementations. Absolute or relative to project directory.	path	`'.py-build-cmake_cache/{build_config}'`
`options`	Extra options passed to the configuration step, as `-D<option>=<value>`. For example: `options = {"WITH_FEATURE_X" = true}`	dict (CMake)	`{}`
`args`	Extra arguments passed to the configuration step. For example: `args = ["--debug-find", "-Wdev"]`	list+	`[]`
`find_python`	Specify hints for CMake's FindPython module. For example: `find_python = false`	bool	`true`
`find_python3`	Specify hints for CMake's FindPython3 module. For example: `find_python3 = false`	bool	`true`
`build_args`	Extra arguments passed to the build step. For example: `build_args = ["-j", "--target", "foo"]`	list+	`[]`
`build_tool_args`	Extra arguments passed to the build tool in the build step (e.g. to Make or Ninja). For example: `build_tool_args = ["--verbose", "-d", "explain"]`	list+	`[]`
`install_config`	Configuration types passed to the install step, as `--config <?>`. You can specify either a single string, or a list of strings. If a multi-config generator is used, all configurations in this list will be included in the package. For example: `install_config = ["Debug", "Release"]`	list	`config`
`install_args`	Extra arguments passed to the install step. For example: `install_args = ["--strip"]`	list+	`[]`
`install_components`	List of components to install, the install step is executed once for each component, with the option `--component <?>`. Use an empty string to specify the default component.	list	`['']`
`env`	Environment variables to set when running CMake. Supports variable expansion using `${VAR}` (but not `$VAR`). For example: `env = { "CMAKE_PREFIX_PATH" = "${HOME}/.local" }`	dict	`{}`

wheel

Defines how to create the Wheel package.

Option	Description	Type	Default
`pure_python`	Indicate that this package contains no platform-specific binaries, only Python scripts and other platform-agnostic files. Setting this value to true causes the Wheel tags to be set to `py3-none-any`, and selects the `purelib` folder instead of `platlib`. If unset, the value depends on whether the `cmake` option is set. For example: `pure_python = true`	bool	`none`
`python_tag`	Override the default Python tag for the Wheel package. If your package contains any Python extension modules, you want to set this to `auto`. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `python_tag = ['py2', 'py3']`	list	`'auto'`
`python_abi`	Override the default ABI tag for the Wheel package. For packages with a Python extension module that make use of the full Python C API, this option should be set to `auto`. If your package does not contain Python extension modules (e.g. because it only includes executables to run as a subprocess, or only shared library files to be loaded using `ctypes`), you can set this to `none`. If your package only includes Python extension modules that use the CPython stable ABI, set this to `abi3` (see also `abi3_minimum_cpython_version` below). For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `python_abi = 'none'`	`'auto'` \| `'none'` \| `'abi3'`	`'auto'`
`abi3_minimum_cpython_version`	If `python_abi` is set to `abi3`, only use the stable CPython API for CPython version that are newer than `abi3_minimum_version`. Useful for nanobind, which supports the stable ABI for CPython 12 and later. This option only applies to CPython using the stable ABI, in which case it has the following effect: the Python tag of the resulting wheel is set to the given version of CPython, and the ABI tag of the wheel is set to ABI3. The Python version is encoded as a single integer, consisting of the major and minor version numbers, without a dot (the same format as the Python tag). This value should match the value of the `Py_LIMITED_API` macro used to build the Python module. For example, if you're using `abi3_minimum_cpython_version=312`, you should set `Py_LIMITED_API=0x030C0000`. If you're using CMake's `Python3_add_library` command, you should specify the `USE_SABI 3.12` option. For example: `abi3_minimum_cpython_version = 312`	int	`32`
`abi_tag`	Override the default ABI tag for the Wheel package. It is not recommended to set this value in your pyproject.toml file directly. Instead, it is intended to be specified from the command line, or in a local override. See also: cross.abi. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `abi_tag = 'pypy310_pp73'`	list	`none`
`platform_tag`	Override the default platform tag for the Wheel package. The special value `guess` tries to select a sensible value based on the environment and the current Python interpreter (not supported when cross-compiling). It is not recommended to set this value in your pyproject.toml file directly. Instead, it is intended to be specified from the command line, or in a local override. See also: cross.arch. There are no checks in place to ensure that the platform tag applies to all files in the Wheel. If possible, you should use a tool such as auditwheel (https://github.com/pypa/auditwheel) or delocate (https://github.com/matthew-brett/delocate) to select the tag and to verify/fix the resulting package. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `platform_tag = 'manylinux_2_35_x86_64'`	list	`none`
`build_tag`	Add an optional build number to the Wheel package. Must start with a number and cannot contain `-` characters. It is not recommended to set this value in your pyproject.toml file directly. Instead, it is intended to be specified from the command line, or in a local override. For details about Wheel build tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-name-convention For example: `build_tag = '1'`	string	`none`

stubgen

If specified, mypy's stubgen utility will be used to generate typed stubs for the Python files in the package.

Option	Description	Type	Default
`packages`	List of packages to generate stubs for, passed to stubgen as -p <?>.	list	`none`
`modules`	List of modules to generate stubs for, passed to stubgen as -m <?>.	list	`none`
`files`	List of files to generate stubs for, passed to stubgen without any flags.	list	`none`
`args`	List of extra arguments passed to stubgen.	list+	`[]`

linux

Override options for Linux.

Option	Description	Default
`editable`	Linux-specific editable options. Inherits from: `/pyproject.toml/tool/py-build-cmake/editable`	`none`
`sdist`	Linux-specific sdist options. Inherits from: `/pyproject.toml/tool/py-build-cmake/sdist`	`none`
`cmake`	Linux-specific CMake options. Inherits from: `/pyproject.toml/tool/py-build-cmake/cmake`	`none`
`wheel`	Linux-specific Wheel options. Inherits from: `/pyproject.toml/tool/py-build-cmake/wheel`	`none`

windows

Override options for Windows.

Option	Description	Default
`editable`	Windows-specific editable options. Inherits from: `/pyproject.toml/tool/py-build-cmake/editable`	`none`
`sdist`	Windows-specific sdist options. Inherits from: `/pyproject.toml/tool/py-build-cmake/sdist`	`none`
`cmake`	Windows-specific CMake options. Inherits from: `/pyproject.toml/tool/py-build-cmake/cmake`	`none`
`wheel`	Windows-specific Wheel options. Inherits from: `/pyproject.toml/tool/py-build-cmake/wheel`	`none`

mac

Override options for Mac.

Option	Description	Default
`editable`	Mac-specific editable options. Inherits from: `/pyproject.toml/tool/py-build-cmake/editable`	`none`
`sdist`	Mac-specific sdist options. Inherits from: `/pyproject.toml/tool/py-build-cmake/sdist`	`none`
`cmake`	Mac-specific CMake options. Inherits from: `/pyproject.toml/tool/py-build-cmake/cmake`	`none`
`wheel`	Mac-specific Wheel options. Inherits from: `/pyproject.toml/tool/py-build-cmake/wheel`	`none`

cross

Causes py-build-cmake to cross-compile the project. See https://tttapa.github.io/py-build-cmake/Cross-compilation.html for more information.

Option	Description	Type	Default
`os`	Operating system configuration to inherit from.	`'linux'` \| `'mac'` \| `'windows'`	`none`
`implementation`	Identifier for the Python implementation. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `implementation = 'cp' # CPython`	string	`same as current interpreter`
`version`	Python version, major and minor, without dots. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `version = '310' # 3.10`	string	`same as current interpreter`
`abi`	Python ABI. For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `abi = 'cp310'`	string	`same as current interpreter`
`arch`	Platform tag, consisting of the operating system and architecture (no dots or dashes, only underscores, all lowercase). For details about platform compatibility tags, see the PyPA specification: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags For example: `arch = 'linux_x86_64'`	string	`same as current interpreter`
`prefix`	Root path of the Python installation. Used to set the `Python3_ROOT_DIR` CMake hint, see https://cmake.org/cmake/help/latest/module/FindPython3.html#hints. Absolute or relative to current configuration file.	path	`none`
`library`	Python library file (.so on Linux, .lib on Windows). Used to set the `Python3_LIBRARY` CMake artifact, see https://cmake.org/cmake/help/latest/module/FindPython3.html#artifacts-specification. Absolute or relative to current configuration file.	filepath	`none`
`include_dir`	Python include directory (containing Python.h). Used to set the `Python3_INCLUDE_DIR` CMake artifact, see https://cmake.org/cmake/help/latest/module/FindPython3.html#artifacts-specification. Absolute or relative to current configuration file.	path	`none`
`toolchain_file`	CMake toolchain file to use. See https://cmake.org/cmake/help/book/mastering-cmake/chapter/Cross%20Compiling%20With%20CMake.html for more information. Absolute or relative to current configuration file.	filepath	`none`
`generator_platform`	The value for CMAKE_GENERATOR_PLATFORM. Only applies to the Visual Studio generator on Windows. See https://cmake.org/cmake/help/latest/variable/CMAKE\_GENERATOR\_PLATFORM.html for details. For example: `generator_platform = 'ARM64'`	string	`none`
`editable`	Override editable options when cross-compiling. Inherits from: `/pyproject.toml/tool/py-build-cmake/editable`		`none`
`sdist`	Override sdist options when cross-compiling. Inherits from: `/pyproject.toml/tool/py-build-cmake/sdist`		`none`
`cmake`	Override CMake options when cross-compiling. Inherits from: `/pyproject.toml/tool/py-build-cmake/cmake`		`none`
`wheel`	Override Wheel options when cross-compiling. Inherits from: `/pyproject.toml/tool/py-build-cmake/wheel`		`none`

Local overrides

Additionally, two extra configuration files can be placed in the same directory as pyproject.toml to override some options for your specific use case:

py-build-cmake.local.toml: the options in this file override the values in the tool.py-build-cmake section of pyproject.toml.
This is useful if you need specific arguments or CMake options to compile the package on your system.
py-build-cmake.cross.toml: the options in this file override the values in the tool.py-build-cmake.cross section of pyproject.toml.
Useful for cross-compiling the package without having to edit the main configuration file.

It is recommended to exclude these files from version control, e.g. by adding them to your .gitignore.

Command-line overrides

Instead of using the py-build-cmake.local.toml and py-build-cmake.cross.toml files, you can also include additional config files using command-line options:

--local: specifies a toml file that overrides the tool.py-build-cmake section of pyproject.toml, similar to py-build-cmake.local.toml
--cross: specifies a toml file that overrides the tool.py-build-cmake.cross section of pyproject.toml, similar to py-build-cmake.cross.toml

These command-line overrides are applied after the py-build-cmake.local.toml and py-build-cmake.cross.toml files in the project folder (if any).

When using PyPA build, these flags can be specified using the -C or --config-setting flag:

python -m build . -C--cross=/path/to/my-cross-config.toml

The same flag may appear multiple times. The order for the same flag is preserved, but all --cross flags are applied after all --local flags. For example:

python -m build . -C--local=conf-A.toml -C--local=conf-B.toml

For PyPA pip, you can use the -C or --config-settings flags instead.

Finally, you can also specify overrides for specific configuration options on the command-line, for example:

python -m build . \
   -C override=cmake.options.CMAKE_PREFIX_PATH+="/opt/some-package" \
   -C override=cmake.env.PATH=+(path)"/opt/some-package/bin"

The format consists of the configuration option keys (separated) by periods, followed by an operator (such as +=, see below), followed by the value.

The following operators are supported:

=: Sets the configuration option regardless of its previous value.
+=: Appends the given value to the previous value.
=+: Prepends the given value to the previous value.
=-: Removes the given value from the previous value.
=!: Clears the configuration option if set.
+=(path): Appends the given value to the previous value, joining them with the system's path separator (: on Unix, ; on Windows).
=+(path): Prepends the given value to the previous value, joining them with the system's path separator.

Values can be specified using a TOML-like syntax, using square brackets for lists, and curly braces with equal signs for dictionaries. Simple strings can be specified without quotes, but quotes are required when including special characters. Note the escaping of quotes to prevent the shell from stripping them out.

python -m build . \
   -C "override=cmake.options.CMAKE_PREFIX_PATH=[\"/opt/some-package\", \"/another\"]" \
   -C "override=cmake.env={MY_PATH = \"/opt/some-package\" }" \
   -C "override=cmake.find_python=true"

Combining lists

Many options are specified as lists of strings. When one of these options inherits from or is overridden by another option, these lists can be merged in different ways.

In the table above, when the data type is list, the original list of options is simply replaced by the list it is overridden by.
When the data type is list+, the value of the overriding option is appended to the original value. This is used primarily for combining lists of command-line options.

If you want full control of what happens when overriding a list option, you can use a dictionary with one or more of the following keys:

"=": replace the original list by this list (default behavior for options of type list)
"+": append the values of this list to the end of the original list (default behavior for options of type list+)
"-": remove the values in this list from the original list (if present)
"prepend": prepend the values of this list to the beginning of the original list

Some examples:

[cmake]
build_args = ["--verbose", "--clean-first"]
[linux.cmake]
build_args = ["--target", "foo"]
[windows.cmake]
build_args = {"-" = ["--verbose"], "+" = ["--target", "bar"]}
[macos.cmake]
build_args = {"=" = ["--target", "macos"]}

Because linux.cmake inherits from cmake, and because build_args has type list+, this will result in a value of ["--verbose", "--clean-first", "--target", "foo"] for the linux.cmake.build_args option. The value of windows.cmake.build_args will be ["--clean_first", "--target", "bar"], and the value of macos.cmake.build_args will be ["--target", "macos"].

[cmake]
config = ["Debug", "Release"]
[linux.cmake]
config = ["RelWithDebInfo"]
[windows.cmake]
config = {"prepend" = ["RelWithDebInfo"], "-" = ["Debug"], "+" = ["Debug"]}

The build_args option has type list, so the value of linux.cmake.config is simply ["RelWithDebInfo"]. The value of windows.cmake.config is ["RelWithDebInfo", "Release", "Debug"].

The same rules also apply to CMake options:

[cmake.options]
CMAKE_PREFIX_PATH = "/some/path"
[linux.cmake.options]
CMAKE_PREFIX_PATH = {"prepend" = "/some/linux-specific/path"}

This passes the option -D CMAKE_PREFIX_PATH=/some/linux-specific/path;/some/path to CMake.

This site is open source. Improve this page.