Config.md

Index

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 (but not '**' for recursive patterns).	list	[]
exclude	Files and folders to exclude from the source distribution. May include the '*' wildcard (but not '**' 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 and install steps, 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: 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_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. 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'	string	'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. The Python version is encoded as a single integer, consisting of the major and minor version numbers, without a dot. For example: abi3_minimum_cpython_version = 312	int	32

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