Configuration options (pyproject.toml)

The main configuration file for py-build-cmake is the standard pyproject.toml file in the root of your project. All py-build-cmake-specific options live in the [tool.py-build-cmake] section of the configuration file. Different subsections control different aspects of the build and packaging process, such as [tool.py-build-cmake.sdist] for source distributions, [tool.py-build-cmake.cmake] for CMake and other build-related options, and [tool.py-build-cmake.wheel] for properties of binary Wheel packages. Detailed descriptions of all available sections and options can be found below.

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 Editable Install / Development Mode 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>. Note that setting CMAKE_OSX_DEPLOYMENT_TARGET here is not supported, see How to set the minimum supported macOS version. 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}. Use a double dollar sign $$ to insert a literal $. Note that setting MACOSX_DEPLOYMENT_TARGET here is not supported, see How to set the minimum supported macOS version. 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 (pypa/auditwheel) or delocate (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

Specific 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

Specific 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

Specific options for macOS.

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

cross

Causes py-build-cmake to cross-compile the project. See Cross-compilation 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 Compiling With CMake.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

---

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.