Configuration#

Scikit-build-core supports a powerful unified configuration system. Every option in scikit-build-core can be specified in one of three ways: as a pyproject.toml option (preferred if static), as a config-settings options (preferred if dynamic), or as an environment variable.

Verbosity#

You can increase the verbosity of the build with two settings - cmake.verbose is a shortcut for verbose build output, and logging.level controls scikit-build-core’s internal logging. An example (with all configuration styles) of setting both is:

pyproject.toml

[tool.scikit-build]
cmake.verbose = true
logging.level = "INFO"

config-settings

pip

$ pip install . -v --config-settings=cmake.verbose=true --config-settings=logging.level=INFO

build

$ pipx run build --wheel -Ccmake.verbose=true -Clogging.level=INFO

cibuildwheel

[tool.cibuildwheel.config-settings]
"cmake.verbose" = true
"logging.level" = "INFO"

Environment

SKBUILD_CMAKE_VERBOSE: true
SKBUILD_LOGGING_LEVEL: "INFO"

Note

When using pip, make sure you include at least a -v argument so that the verbosity settings above are displayed.

Warning

In general, the environment variable method is intended as an emergency workaround for legacy tooling.

Minimum version & defaults#

Scikit-build-core, like CMake, has a special minimum required version setting. If you set this, you get two benefits. First, if the version is less than this version, you get a nice error message. But, more importantly, if scikit-build-core is a newer version than the version set here, it will select older defaults to help ensure your package can continue to build, even if a default value changes in the future. This should help reduce the chance of ever needed an upper cap on the scikit-build-core version, as upper caps are discouraged.

It is recommended you set this value as high as you feel comfortable with, and probably keep in sync with your build-system requirements.

[tool.scikit-build]
minimum-version = "0.2"

Warning

The following behaviors are affected by minimum-version:

minimum-version 0.5+ (or unset) provides the original name in metadata and properly normalized SDist names.
minimum-version 0.5+ (or unset) strips binaries by default.

CMake and Ninja minimum versions#

You can select a different minimum version for CMake and Ninja. Scikit-build-core will automatically decide to download a wheel for these (if possible) when the system version is less than this value.

For example, to require a recent CMake and Ninja:

[tool.scikit-build]
cmake.minimum-version = "3.26.1"
ninja.minimum-version = "1.11"

You can also enforce ninja to be required even if make is present on Unix:

[tool.scikit-build]
ninja.make-fallback = false

You can also control the FindPython backport; by default, a backport of CMake 3.26.1’s FindPython will be used if the CMake version is less than 3.26.1; you can turn this down if you’d like (“3.15”, scikit-build-core’s minimum version, would turn it off).

[tool.scikit-build]
backport.find-python = "3.15"

Configuring source file inclusion#

Scikit-build-core defaults to using your .gitignore to select what to exclude from the source distribution. You can list files to explicitly include and exclude if you want:

[tool.scikit-build]
sdist.include = ["src/some_generated_file.txt"]
sdist.exclude = [".github"]

By default, scikit-build-core will respect SOURCE_DATE_EPOCH, and will lock the modification time to a reproducible value if it’s not set. You can disable reproducible builds if you prefer, however:

[tool.scikit-build]
sdist.reproducible = false

You can also request CMake to run during this step:

[tool.scikit-build]
sdist.cmake = true

Note

If you do this, you’ll want to have some artifact from the configure in your source directory; for example:

include(FetchContent)

if(NOT SKBUILD_STATE STREQUAL "sdist"
   AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/pybind11/CMakeLists.txt")
  message(STATUS "Using integrated pybind11")
  set(FETCHCONTENT_FULLY_DISCONNECTED ON)
endif()

FetchContent_Declare(
  pybind11
  GIT_REPOSITORY https://github.com/pybind/pybind11.git
  GIT_TAG v2.11.1
  SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/pybind11)

set(PYBIND11_FINDPYTHON ON)
FetchContent_MakeAvailable(pybind11)

The /pybind11 directory is in the .gitignore and important parts are in sdist.include:

[tool.scikit-build]
sdist.cmake = true
sdist.include = [
  "pybind11/tools",
  "pybind11/include",
  "pybind11/CMakeLists.txt",
]

Customizing the built wheel#

The wheel will automatically look for Python packages at src/<package_name>, python/<package_name>, and <package_name>, in that order. If you want to list packages explicitly, you can. The final path element is the package.

[tool.scikit-build]
wheel.packages = ["python/src/mypackage"]

Or you can disable Python file inclusion entirely, and rely only on CMake’s install mechanism, you can do that instead:

[tool.scikit-build]
wheel.packages = []

The install directory is normally site-packages; however, you can manually set that to a different directory if you’d like to avoid changing your CMake files. For example, to mimic scikit-build classic:

[tool.scikit-build]
wheel.install-dir = "mypackage"

Warning

You can select a different wheel target directory, as well, but that syntax is experimental; install to ${SKBUILD_DATA_DIR}, etc. from within CMake instead for now.

By default, any LICEN[CS]E*, COPYING*, NOTICE*, or AUTHORS* file in the root of the build directory will be picked up. You can specify an exact list of files if you prefer, or if your license file is in a different directory. Globbing patterns are supported.

[tool.scikit-build]
wheel.license-files = ["LICENSE"]

Dynamic metadata#

Scikit-build-core 0.3.0+ supports dynamic metadata with two built-in plugins.

Warning

This is not ready for plugin development outside of scikit-build-core; tool.scikit-build.experimental=true is required to use plugins that are not shipped with scikit-build-core, since the interface is provisional and may change between minor versions.

Setuptools-scm

You can use setuptools-scm to pull the version from VCS:

[project]
name = "mypackage"
dynamic = ["version"]

[tool.scikit-build]
metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
sdist.include = ["src/package/_version.py"]

[tool.setuptools_scm]  # Section required
write_to = "src/package/_version.py"

This sets the python project version according to git tags or a .git_archival.txt file, or equivalents for other VCS systems.

If you need to set the CMake project version without scikit-build-core (which provides ${SKBUILD_PROJECT_VERSION}), you can use something like DynamicVersion module from github.com/LecrisUT/CMakeExtraUtils:

# Import `CMakeExtraUtils` or bundle `DynamicVersion.cmake` from there
include(DynamicVersion)

# Set ${PROJECT_VERSION} according to git tag or `.git_archival.txt`
dynamic_version()

project(MyPackage VERSION ${PROJECT_VERSION})

Fancy-pypi-readme

You can use hatch-fancy-pypi-readme to render your README:

[project]
name = "mypackage"
dynamic = ["readme"]

[tool.scikit-build]
metadata.readme.provider = "scikit_build_core.metadata.fancy_pypi_readme"

# tool.hatch.metadata.hooks.fancy-pypi-readme options here

Regex

If you want to pull a string-valued expression (usually version) from an existing file, you can the integrated regex plugin to pull the information.

name = "mypackage"
dynamic = ["version"]

[tool.scikit-build.metadata.version]
provider = "scikit_build_core.metadata.regex"
input = "src/mypackage/__init__.py"

You can set a custom regex with regex=; use (?P<value>...) to capture the value you want to use. By default when targeting version, you get a reasonable regex for python files, '(?i)^(__version__|VERSION) *= *([\'"])v?(?P<value>.+?)\2'.

New in version 0.5.

Writing metadata#

You can write out metadata to file(s) as well. Other info might become available here in the future, but currently it supports anything available as strings in metadata. (Note that arrays like this are only supported in TOML configuration.)

[[tool.scikit-build.generate]]
path = "package/_version.py"
template = '''
version = "${version}"
'''

template or template-path is required; this uses string.Template formatting. There are three options for output location; location = "install" (the default) will go to the wheel, location = "build" will go to the CMake build directory, and location = "source" will write out to the source directory (be sure to .gitignore this file. It will automatically be added to your SDist includes. It will overwrite existing files).

The path is generally relative to the base of the wheel / build dir / source dir, depending on which location you pick.

Editable installs#

Experimental support for editable installs is provided, with some caveats and configuration. Recommendations:

Use --no-build-isolation when doing an editable install is recommended; you should preinstall your dependencies.
Automatic rebuilds do not have the original isolated build dir (pip deletes it).
Select a build-dir when using editable installs, especially if you also enable automatic rebuilds.
You need to reinstall to pick up new files.

Known limitations:

Resources (via importlib.resources) are not properly supported (yet).

# Very experimental rebuild on initial import feature
$ pip install --no-build-isolation --config-settings=editable.rebuild=true -ve.

Due to the length of this line already being long, you do not need to set the experimental setting to use editable installs, but please consider them experimental and subject to change.

You can disable the verbose rebuild output with editable.verbose=false if you want. (Also available as the SKBUILD_EDITABLE_VERBOSE envvar when importing; this will override if non-empty, and "0" will disable verbose output).

Currently one editable.mode is provided, "redirect", which uses a custom redirecting finder to combine the static CMake install dir with the original source code. Python code added via scikit-build-core’s package discovery will be found in the original location, so changes there are picked up on import, regardless of the editable.rebuild setting.

Other options#

You can select a custom build dir; by default scikit-build-core will use a temporary dir. If you select a persistent one, you can get major rebuild speedups.

pyproject.toml

[tool.scikit-build]
build-dir = "build/{wheel_tag}"

config-settings

pip

$ pip install . --config-settings=build-dir="build/{wheel_tag}"

build

$ pipx run build --wheel -Cbuild-dir="build/{wheel_tag}"

cibuildwheel

[tool.cibuildwheel.config-settings]
"build-dir" = "build/{wheel_tag}"

Environment

SKBUILD_BUILD_DIR: "build/{wheel_tag}"

There are several values you can access through Python’s formatting syntax:

cache_tag: sys.implementation.cache_tag
wheel_tag: The tags as computed for the wheel
build_type: The current build type (Release by default)
state: The current run state, sdist, wheel, editable, metadata_wheel, and metadata_editable

Scikit-build-core also strictly validates configuration; if you need to disable this, you can:

[tool.scikit-build]
strict-config = false

Scikit-build-core also occasionally has experimental features. This is applied to features that do not yet carry the same forward compatibility (using minimum-version) guarantee that other scikit-build-core features have. These can only be used if you enable them:

[tool.scikit-build]
experimental = true

Full schema#

The full schema for the tool.scikit-build table is below:

https://github.com/scikit-build/scikit-build-core/blob/main/src/scikit_build_core/resources/scikit-build.schema.json
Scikit-build-core’s settings.
type	object
properties
cmake	type	object
	properties
	minimum-version	The minimum version of CMake to use. If CMake is not present on the system or is older than this, it will be downloaded via PyPI if possible. An empty string will disable this check.
		type	string
		default	3.15
	args	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`.
		type	array
		items	type	string
	define	A table of defines to pass to CMake when configuring the project. Additive.
		type	object
		patternProperties
		.+	oneOf	type	string
				type	boolean
	verbose	Verbose printout when building.
		type	boolean
		default	False
	build-type	The build type to use when building the project. Valid options are: “Debug”, “Release”, “RelWithDebInfo”, “MinSizeRel”, “”, etc.
		type	string
		default	Release
	source-dir	The source directory to use when building the project. Currently only affects the native builder (not the setuptools plugin).
		type	string
		default	.
	targets	The build targets to use when building the project. Empty builds the default target.
		type	array
		items	type	string
	additionalProperties	False
ninja	type	object
	properties
	minimum-version	The minimum version of Ninja to use. If Ninja is not present on the system or is older than this, it will be downloaded via PyPI if possible. An empty string will disable this check.
		type	string
		default	1.5
	make-fallback	If CMake is not present on the system or is older required, it will be downloaded via PyPI if possible. An empty string will disable this check.
		type	boolean
		default	True
	additionalProperties	False
logging	type	object
	properties
	level	The logging level to display, “DEBUG”, “INFO”, “WARNING”, and “ERROR” are possible options.
		enum	NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL
		default	WARNING
	additionalProperties	False
sdist	type	object
	properties
	include	Files to include in the SDist even if they are skipped by default. Supports gitignore syntax.
		type	array
		items	type	string
	exclude	Files to exclude from the SDist even if they are included by default. Supports gitignore syntax.
		type	array
		items	type	string
	reproducible	If set to 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.
		type	boolean
		default	True
	cmake	If set to True, CMake will be run before building the SDist.
		type	boolean
		default	False
	additionalProperties	False
wheel	type	object
	properties
	packages	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.
		type	array
		items	type	string
	py-api	The Python tags. The default (empty string) will use the default Python version. You can also set this to “cp37” to enable the CPython 3.7+ 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.
		type	string
		default
	expand-macos-universal-tags	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.
		type	boolean
		default	False
	install-dir	The install directory for the wheel. This is relative to the platlib root. You might set this to the package name. The original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are available). EXPERIMENTAL: An absolute path will be one level higher than the platlib root, giving access to “/platlib”, “/data”, “/headers”, and “/scripts”.
		type	string
		default
	license-files	A list of license files to include in the wheel. Supports glob patterns.
		type	array
		items	type	string
	additionalProperties	False
backport	type	object
	properties
	find-python	If CMake is less than this value, backport a copy of FindPython. Set to 0 disable this, or the empty string.
		type	string
		default	3.26.1
	additionalProperties	False
editable	type	object
	properties
	mode	Select the editable mode to use. Currently only “redirect” is supported.
		enum	redirect
		default	redirect
	verbose	Turn on verbose output for the editable mode rebuilds.
		type	boolean
		default	True
	rebuild	Rebuild the project when the package is imported. The build-directory must be set.
		type	boolean
		default	False
	additionalProperties	False
install	type	object
	properties
	components	The components to install. If empty, all default components are installed.
		type	array
		items	type	string
	strip	Whether to strip the binaries. True for scikit-build-core 0.5+.
		type	boolean
	additionalProperties	False
generate	type	array
	items	oneOf	type	object
			properties
			path	The path (relative to platlib) for the file to generate.
				type	string
				minLength	1
			template	The template to use for the file. This includes string.Template style placeholders for all the metadata. If empty, a template-path must be set.
				type	string
				minLength	1
			location	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.
				enum	install, build, source
				default	install
			additionalProperties	False
			type	object
			properties
			path	The path (relative to platlib) for the file to generate.
				type	string
				minLength	1
			template-path	The path to the template file. If empty, a template must be set.
				type	string
				minLength	1
			location	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.
				enum	install, build, source
				default	install
			additionalProperties	False
metadata	List dynamic metadata fields and hook locations in this table.
	type	object
	patternProperties
	.+	type	object
strict-config	Strictly check all config options. If False, warnings will be printed for unknown options. If True, an error will be raised.
	type	boolean
	default	True
experimental	Enable early previews of features not finalized yet.
	type	boolean
	default	False
minimum-version	If set, this will provide a method for backward compatibility.
	type	string
build-dir	The build directory. Defaults to a temporary directory, but can be set.
	type	string
	default
additionalProperties	False

Configuration#

Verbosity#

Minimum version & defaults#

CMake and Ninja minimum versions#

Configuring source file inclusion#

Customizing the built wheel#

Customizing the output wheel#

Configuring CMake arguments and defines#

Dynamic metadata#

Writing metadata#

Editable installs#

Other options#

Full schema#