Config Reference

The following are the available configurations in pyproject.toml for the [tool.scikit-build] table. These can be passed in one of the following ways

[tool.scikit-build]
build.verbose = true
$ pip install . --config-settings=build.verbose=true
$ pipx run build --wheel -Cbuild.verbose=true
[tool.cibuildwheel.config-settings]
"build.verbose" = true
$ export SKBUILD_BUILD_VERBOSE="true"

(top-level)

build-dir
Type:
str

The CMake build directory. Defaults to a unique temporary directory.

This can be set to reuse the build directory from previous runs.

experimental
Type:
bool
Default:
false

Enable early previews of features not finalized yet.

fail
Type:
bool
Default:
false

Immediately fail the build. This is only useful in overrides.

metadata
Type:
dict[str,dict[str,Any]]

List dynamic metadata fields and hook locations in this table.

minimum-version
Type:
Version
Default:
"0.11" # current version

If set, this will provide a method for backward compatibility.

strict-config
Type:
bool
Default:
true

Strictly check all config options.

If False, warnings will be printed for unknown options.

If True, an error will be raised.

backport

backport.find-python
Type:
Version
Default:
"3.26.1"

If CMake is less than this value, backport a copy of FindPython.

Set to 0 or an empty string to disable this.

build

build.requires
Type:
list[str]

Additional build-system.requires.

Intended to be used in combination with overrides.

build.targets
Type:
list[str]

The build targets to use when building the project.

If not specified or an empty list, the default target is used.

build.tool-args
Type:
list[str]

Extra args to pass directly to the builder in the build step.

build.verbose
Type:
bool
Default:
false

Verbose printout when building.

Equivalent to CMAKE_VERBOSE_MAKEFILE.

cmake

cmake.args
Type:
list[str]

A list of args to pass to CMake when configuring the project.

Setting this in config or envvar will override toml.

See also

cmake.define

cmake.build-type
Type:
str
Default:
"Release"

The build type to use when building the project.

Pre-defined CMake options are: Debug, Release, RelWithDebInfo, MinSizeRel

Custom values can also be used.

cmake.define
Type:
EnvVar

A table of defines to pass to CMake when configuring the project. Additive.

cmake.minimum-version
Type:
Version

DEPRECATED in 0.8; use version instead.

cmake.source-dir
Type:
Path
Default:
"."

The source directory to use when building the project.

Currently only affects the native builder (not the setuptools plugin).

cmake.targets
Type:
list[str]

DEPRECATED in 0.10; use build.targets instead.

cmake.verbose
Type:
bool

DEPRECATED in 0.10, use build.verbose instead.

cmake.version
Type:
SpecifierSet

The versions of CMake to allow as a python-compatible specifier.

If CMake is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible with the equivalent specifier used.

An empty string will disable this check.

Special cases:
  • On scikit-build-core 0.10+ CMakeLists.txt is the default value otherwise it’s >=3.15.

  • If CMakeLists.txt is passed, the cmake_minimum_required is read from the CMakeLists.txt file, using that as the minimum specifier. If the file fails to read, >=3.15 is used instead.

See also

ninja.version

editable

editable.mode
Type:
"redirect" | "inplace"
Default:
"redirect"

Select the editable mode to use. Can be “redirect” (default) or “inplace”.

editable.rebuild
Type:
bool
Default:
false

Rebuild the project when the package is imported.

build-dir must be set.

editable.verbose
Type:
bool
Default:
true

Turn on verbose output for the editable mode rebuilds.

generate[]

generate[].location
Type:
"install" | "build" | "source"
Default:
"install"

The place to put the generated file.

The build directory is useful for CMake files, and the install directory is useful for Python files, usually. You can also write directly to the source directory, will overwrite existing files & remember to gitignore the file.

generate[].path
Type:
Path

The path (relative to platlib) for the file to generate.

generate[].template
Type:
str

The template string to use for the file.

Template style placeholders are available for all the metadata.

Either this or generate[].template-path must be set.

generate[].template-path
Type:
Path

The path to the template file. If empty, a template must be set.

Either this or generate[].template must be set.

install

install.components
Type:
list[str]

The components to install.

If not specified or an empty list, all default components are installed.

install.strip
Type:
bool
Default:
true

Whether to strip the binaries.

Equivalent to --strip in cmake install.

True for release builds (Release or MinSizeRel) on scikit-build-core 0.5+.

Note

0.5-0.10.5 also incorrectly set this for debug builds.

logging

logging.level
Type:
"NOTSET" | "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL"
Default:
"WARNING"

The logging level to display.

messages

messages.after-failure
Type:
str

A message to print after a build failure.

messages.after-success
Type:
str

A message to print after a successful build.

ninja

ninja.make-fallback
Type:
bool
Default:
true

Use Make as a fallback if a suitable Ninja executable is not found.

If Make is also not available on the system, a ninja dependency is added to the build-system.requires according to ninja.version.

See also

ninja.version

ninja.minimum-version
Type:
Version

DEPRECATED in 0.8; use version instead.

ninja.version
Type:
SpecifierSet
Default:
">=1.5"

The versions of Ninja to allow.

If Ninja is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible with the equivalent specifier used.

An empty string will disable this check.

sdist

sdist.cmake
Type:
bool
Default:
false

If set to True, CMake will be run before building the SDist.

sdist.exclude
Type:
list[str]

Files to exclude from the SDist even if they are included by default. Supports gitignore syntax.

See also

sdist.include

sdist.include
Type:
list[str]

Files to include in the SDist even if they are skipped by default. Supports gitignore syntax.

Always takes precedence over sdist.exclude

See also

sdist.exclude

sdist.reproducible
Type:
bool
Default:
true

Try to build a reproducible distribution.

Unix and Python 3.9+ recommended.

SOURCE_DATE_EPOCH will be used for timestamps, or a fixed value if not set.

wheel

wheel.build-tag
Type:
str

The build tag to use for the wheel. If empty, no build tag is used.

wheel.cmake
Type:
bool
Default:
true

Run CMake as part of building the wheel.

wheel.exclude
Type:
list[str]

A set of patterns to exclude from the wheel.

This is additive to the SDist exclude patterns. This applies to the final paths in the wheel, and can exclude files from CMake output as well. Editable installs may not respect this exclusion.

wheel.expand-macos-universal-tags
Type:
bool
Default:
false

Fill out extra tags that are not required.

This adds “x86_64” and “arm64” to the list of platforms when “universal2” is used, which helps older Pip’s (before 21.0.1) find the correct wheel.

wheel.install-dir
Type:
str

The CMake install prefix relative to the platlib wheel path.

You might set this to the package name to install everything under the package namespace in a pythonic design.

The original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are available).

Warning

EXPERIMENTAL An absolute path will be one level higher than the platlib root, giving access to “/platlib”, “/data”, “/headers”, and “/scripts”.

wheel.license-files
Type:
list[str]

A list of license files to include in the wheel. Supports glob patterns.

The default is ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"].

Warning

Must not be set if project.license-files is set.

wheel.packages
Type:
list[str]
Default:
["src/<package>", "python/<package>", "<package>"]

A list of packages to auto-copy into the wheel.

If this is not set, it will default to the first of src/<package>, python/<package>, or <package> if they exist. The prefix(s) will be stripped from the package name inside the wheel.

If a dict, provides a mapping of package name to source directory.

wheel.platlib
Type:
bool

Target the platlib or the purelib.

If not set, the default is to target the platlib if wheel.cmake is true, and the purelib otherwise.

wheel.py-api
Type:
str

The Python version tag used in the wheel file.

The default (empty string) will use the default Python version.

You can also set this to “cp38” to enable the CPython 3.8+ Stable ABI / Limited API (only on CPython and if the version is sufficient, otherwise this has no effect). Or you can set it to “py3” or “py2.py3” to ignore Python ABI compatibility. The ABI tag is inferred from this tag.

This value is used to construct SKBUILD_SABI_COMPONENT CMake variable.