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. Note that config-settings options can optionally be prefixed with skbuild., for example -C skbuild.logging.level=INFO.

Verbosity¶

By default, the CMake configuration output is always shown, but it may be hidden behind the build frontend setting, e.g. pip requires including -v argument in order to display any output.

You can increase the verbosity of the build with two settings - build.verbose is a shortcut for verbose build output (i.e. cmake --build ... -v), 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]
build.verbose = true
logging.level = "INFO"

config-settings

pip

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

build

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

cibuildwheel

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

Environment

SKBUILD_BUILD_VERBOSE: true
SKBUILD_LOGGING_LEVEL: "INFO"

Warning

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

Changed in version 0.10: cmake.verbose was renamed to build.verbose.

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.12"

In your pyproject.toml, you can specify the special string "build-system.requires", which will read the minimum version from your build-system requirements directly; you must specify a minimum there to use this automatic feature.

[build-system]
requires = ["scikit-build-core>=0.12"]

[tool.scikit-build]
minimum-version = "build-system.requires"

Changed in version 0.10: The "build-system.requires" option was added.

Warning

The following behaviors are affected by minimum-version:

minimum-version 0.5+ (or unset) strips binaries by default.
minimum-version 0.8+ (or unset) cmake.minimum-version and ninja.minimum-version are replaced with cmake.version and ninja.version.
minimum-version 0.10+ (or unset) cmake.targets and cmake.verbose are replaced with build.targets and build.verbose. The CMake minimum version will be detected if not given.
minimum-version 0.12+ (or unset) uses "default" instead of "classic" as the default for sdist.include-mode.
minimum-version 1.0+ (or unset) deprecates the tool.scikit-build.metadata table in favor of the standard top-level [[tool.dynamic-metadata]]; see Dynamic metadata.

Changed in version 0.12.2: Non-normalized SDist names used to be enabled when set to below 0.5. This is no longer supported on PyPI, so this back-compat feature was removed.

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.version = ">=3.26.1"
ninja.version = ">=1.11"

You can try to read the version from your CMakeLists.txt with the special string "CMakeLists.txt". This is an error if the minimum version was not statically detectable in the file. If your minimum-version setting is unset or set to “0.10” or higher, scikit-build-core will still try to read this if possible, and will fall back on “>=3.15” if it can’t read it.

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 supported CMake version, would turn it off).

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

Added in version 0.8: These used to be called cmake.minimum-version and ninja.minimum-version, and only took a single value. Now they are full specifier sets, allowing for more complex version requirements, like >=3.15,!=3.18.0.

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"]

You can select a couple of alternative modes, as well. If you want to manually control this, without reading .gitignore, use:

[tool.scikit-build]
sdist.include-mode = "manual"

There’s also a "classic" mode, which fully traverses all directories to check rules (this was the default before scikit-build-core 0.12).

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)

set(PYBIND11_FINDPYTHON ON)

if(NOT SKBUILD_STATE STREQUAL "sdist"
   AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/pybind11/CMakeLists.txt")
  message(STATUS "Using integrated pybind11")
  add_subdirectory(pybind11)
else()
  FetchContent_Declare(
    pybind11
    GIT_REPOSITORY https://github.com/pybind/pybind11.git
    GIT_TAG v2.12.0
    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/pybind11)
  FetchContent_MakeAvailable(pybind11)
endif()

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, where <package_name> is your project’s name. If you want to list packages explicitly, you can. The final path element is the package.

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

Each entry names a single top-level package directory, and the final path element becomes the importable package name. This is not a search directory like setuptools’ tool.setuptools.packages.find.where: subpackages and data files inside a listed package are copied in automatically (recursively), so you never list subpackages. To ship two separate top-level packages, list both:

[tool.scikit-build]
wheel.packages = ["src/pkg_a", "src/pkg_b"]

Auto-detection only looks for a package matching your project name at the three locations above; if you have multiple top-level packages, or your package lives elsewhere, you must list them explicitly.

This can also be a table, allowing full customization of where a source package maps to a wheel directory. The final components of both paths must match due to the way editable installs work. The equivalent of the above is:

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

But you can also do more complex moves:

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

Added in version 0.10: Support for the table form.

You can disable Python file inclusion entirely, and rely only on CMake’s install mechanism:

[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"

You can target a different wheel tree by prefixing the install dir with the matching SKBUILD_*_DIR CMake variable name:

[tool.scikit-build]
wheel.install-dir = "${SKBUILD_DATA_DIR}/mypackage"

The available trees are ${SKBUILD_PLATLIB_DIR} (the default), ${SKBUILD_PURELIB_DIR}, ${SKBUILD_DATA_DIR}, ${SKBUILD_HEADERS_DIR}, ${SKBUILD_SCRIPTS_DIR}, ${SKBUILD_METADATA_DIR}, and ${SKBUILD_NULL_DIR}. This matches the cache variables available from within CMake.

Added in version 1.0: Targeting other wheel trees with the ${SKBUILD_<TREE>_DIR} prefix.

Warning

When passing this through PEP 517 config-settings on a command line, quote it so the shell does not expand ${SKBUILD_DATA_DIR} as an environment variable (e.g. -C 'wheel.install-dir=${SKBUILD_DATA_DIR}/mypackage').

The older leading-slash spelling (/data, /scripts, …) selects the same trees but is gated behind experimental = true, and deprecated.

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"]

You can exclude files from the built wheel (on top of the sdist.exclude list) as well (not guaranteed to be respected by editable installs):

[tool.scikit-build]
wheel.exclude = ["**.pyx"]

Changed in version 0.9: Previously these were matched on the source path, rather than the wheel path, and didn’t apply to CMake output.

Note

There are two more settings that are primarily intended for overrides (see below). wheel.cmake defaults to true, and this enables/disables building with CMake. It also changes the default of wheel.platlib unless it’s set explicitly; CMake builds assume wheel.platlib = true, and CMake-less builds assume wheel.platlib = false (purelib targeted instead).

Force-including files¶

Added in version 1.0.

Sometimes you need to place a specific file (or directory) at a specific path in a distribution, even if it lives outside your package tree or is produced elsewhere. Each distribution has its own force-include table mapping source paths to destinations:

[tool.scikit-build.sdist.force-include]
"../shared/data.json" = "mypackage/data.json"

[tool.scikit-build.wheel.force-include]
"vendor/lib.so" = "mypackage/_lib.so"
"tools/run.sh"  = "${SKBUILD_SCRIPTS_DIR}/run.sh"

The keys are source paths relative to the project root; they may point outside it (e.g. ../shared) or be absolute, and ~ is expanded. A source may be a file or a directory, and directories are copied recursively (skipping VCS and __pycache__ junk). A missing source is an error.

sdist.force-include destinations are relative to the SDist root. wheel.force-include destinations are relative to the platlib (the package area), and also accept a ${SKBUILD_<TREE>_DIR} prefix (e.g. ${SKBUILD_DATA_DIR}, ${SKBUILD_SCRIPTS_DIR}, ${SKBUILD_HEADERS_DIR}, ${SKBUILD_METADATA_DIR}) to target that wheel tree instead, matching the SKBUILD_*_DIR CMake cache variables. The older leading-slash spelling (/data, /scripts, …) does the same but requires experimental = true. Force-included wheel files are placed last, so they override discovered package files and CMake output at the same destination.

A force-included file also overrides the matching exclude list (wheel.exclude for wheels, sdist.exclude for SDists): naming an exact source is an explicit request, so it wins even if an exclude pattern matches its destination. A force-included directory stays subject to that exclude, so a bulk tree copy can still be trimmed by an exclude pattern (e.g. force-include a directory and exclude **/*.bzl to drop the Bazel files from it).

Building a wheel from an SDist¶

A common pattern vendors an external (../) source into the SDist and then ships that output in the wheel. Reference the SDist destination as the wheel source and it works in both build modes:

[tool.scikit-build.sdist.force-include]
"../shared/data.json" = "mypackage/data.json"   # vendor it into the SDist

[tool.scikit-build.wheel.force-include]
"mypackage/data.json" = "mypackage/data.json"    # ship the SDist output

When the wheel is built from the unpacked SDist, mypackage/data.json exists and is used directly. When it is built from the source tree (or an editable install) the file was never materialized; a wheel.force-include source missing on disk is then resolved through sdist.force-include (by exact destination, or under a force-included directory) and read from that original source instead. An on-disk file always wins, so the vendored copy is preferred when present.

For cases the automatic resolution cannot express — e.g. the wheel source is the original external path rather than the SDist output — use overrides keyed on from-sdist, with a separate wheel.force-include entry gated on each build mode (source tree vs. wheel-from-SDist):

[tool.scikit-build.sdist.force-include]
"../outside.txt" = "vendored/blob.txt"   # vendor it into the SDist

[[tool.scikit-build.overrides]]
if.from-sdist = false                     # source-tree build: read the original
wheel.force-include."../outside.txt" = "mypackage/blob.txt"

[[tool.scikit-build.overrides]]
if.from-sdist = true                      # wheel-from-SDist: read the vendored copy
wheel.force-include."vendored/blob.txt" = "mypackage/blob.txt"

Environment variables for the build¶

Added in version 1.0.

The [tool.scikit-build.env] table sets environment variables for the CMake configure, build, and install subprocesses. Use it for things CMake or the generator read from the environment — CC/CXX, CFLAGS, CMAKE_PREFIX_PATH, compiler launchers, parallel-build level, and so on. For CMake -D cache entries, use cmake.define instead.

Each value is a literal string, or a table that reads from another environment variable ({ env = "OTHER", default = "..." }). By default a variable is only set if it is not already present (setdefault); add force = true to overwrite an existing value. If a value resolves to nothing (its env source is unset and there is no default), the key is skipped. This pairs well with [[tool.scikit-build.overrides]] for platform- or state-specific values.

[tool.scikit-build.env]
SOME_VAR = "some-value"
CMAKE_PREFIX_PATH = { env = "CMAKE_PREFIX_PATH", default = "/opt/mydeps" }

A common use is forwarding a project’s historical parallelism variable (such as MAX_JOBS) to CMAKE_BUILD_PARALLEL_LEVEL:

[tool.scikit-build.env]
CMAKE_BUILD_PARALLEL_LEVEL = { env = "MAX_JOBS" }

A directly-set CMAKE_BUILD_PARALLEL_LEVEL still wins, since env entries use setdefault semantics unless force = true is given.

Note

This table is independent of the if.env override condition. if.env only matches against the ambient process environment and does not see variables you define here.

The table form ({ env = ..., default = ..., force = ... }) is pyproject.toml only; via config-settings or SKBUILD_ENV_* you can only set a literal value.

Selecting a compiler¶

To pick a specific compiler — for example, to use GCC instead of MSVC on a Windows runner — set CC/CXX, optionally scoped to a platform with an override:

[[tool.scikit-build.overrides]]
if.platform-system = "win32"
env.CC = "gcc"
env.CXX = "g++"

These take precedence over the compiler scikit-build-core would otherwise pull from Python’s sysconfig, even without force.

By default, scikit-build-core sets CC/CXX from Python’s sysconfig compiler when they are not already set. If a project’s compiler probes break on that compiler (a conda narrow sysroot, a stale venv gcc, a cross or oneAPI toolchain), list the variable in the env table to suppress that default and let CMake detect the compiler from PATH — an entry that reads from the same name does this without pinning a value:

[tool.scikit-build.env]
CC = { env = "CC" }
CXX = { env = "CXX" }

Search paths for dependencies¶

To point CMake at extra prefixes (vcpkg, Homebrew, a custom install tree) when locating dependencies, set CMAKE_PREFIX_PATH:

[tool.scikit-build.env]
CMAKE_PREFIX_PATH = "/opt/mydeps;/usr/local"

Editable installs¶

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), so select a build-dir when using editable installs, especially if you also enable automatic rebuilds.
You need to reinstall to pick up new files.

Resources (via importlib.resources) are supported and tested on all supported Python versions. On Python 3.8, use the importlib_resources backport, since importlib.resources.files was added to the standard library in Python 3.9.

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

The automatic rebuild-on-import feature (editable.rebuild) is still 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).

When editable.rebuild is enabled together with a persistent build-dir, the CMake install targets a tree inside the build directory and the redirecting finder loads the compiled artifacts from there directly, rather than from copies in site-packages. This means SKBUILD_PLATLIB_DIR (or SKBUILD_PURELIB_DIR) and CMAKE_INSTALL_PREFIX are baked at their final location when the editable wheel is first built, so import-triggered rebuilds re-install in place with no extra reconfigure – including projects that install to an absolute ${SKBUILD_PLATLIB_DIR}/... destination. Deleting the build directory breaks the install, but a rebuildable editable already depends on it.

As a newer, parallel alternative, editable.rebuild-dir selects the install tree directly and turns on rebuild-on-import by itself (the editable.rebuild flag is ignored when it is set). It accepts the same template substitutions as build-dir, and the path must be absolute, or relative to the source directory, and stable between build and run time, since it is baked at configure time and referenced by absolute path on rebuild. This only moves the install tree; build-dir is still required and still hosts the CMake build that the rebuild re-runs. The classic editable.rebuild (which installs into a tree inside build-dir) is left as-is, so the two approaches can be compared.

Added in version 1.0: editable.rebuild-dir, a persistent install tree for editable rebuilds.

The default editable.mode, "redirect", 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.

Changed in version 1.0: PEP 829 .start files are emitted for the redirecting finder on Python 3.15+. Older interpreters emit only .pth files.

Note

A second mode, "inplace", is also available. This does an in-place CMake build, so all the caveats there apply too – only one build per source directory, you can’t change to an out-of-source builds without removing the build artifacts, your source directory will be littered with build artifacts, etc. Also, to make your binaries importable, you should set LIBRARY_OUTPUT_DIRECTORY (include a generator expression, like the empty one $<0:> for multi-config generator support, like MSVC, so you don’t have to set all possible *_<CONFIG> variations) to make sure they are placed inside your source directory inside the Python packages; this will be run from the build directory, rather than installed. The build directory setting will be ignored if you use this and perform an editable install (the source directory doubles as the build directory). You can detect this mode by checking for an in-place build and checking SKBUILD being set.

With all the caveats, this is very logically simple (one directory) and a near identical replacement for python setup.py build_ext --inplace. Some third party tooling might work better with this mode. Scikit-build-core will simply install a .pth file that points at your source package(s) and do an inplace CMake build.

On the command line, you can pass -Ceditable.mode=inplace to enable this mode. Inplace installs support both automatic (editable.rebuild) and manual rebuilds (see below); since the source directory doubles as the build directory, no separate build-dir is needed.

Triggering a rebuild manually¶

You don’t have to enable editable.rebuild to rebuild on demand. Both editable modes install a loader that exposes a rebuild() method, so you can recompile whenever you like:

import some_package

some_package.__loader__.rebuild()

For redirect installs this runs the same cmake --build/--install cycle used by the automatic rebuild, and works for any importable object the install provides – a package, a plain module, or a compiled extension. A redirect rebuild needs a persistent build directory, so install with a build-dir set:

$ pip install --no-build-isolation -Cbuild-dir=build -ve .

If a redirect editable was built without a persistent build-dir, there is nothing to rebuild and the call raises RuntimeError.

For inplace installs, rebuild() runs cmake --build in the source tree (there is no install step); the source directory is always the build directory, so no build-dir is required.

If you don’t have a handle on a redirected module, the finder itself is on sys.meta_path and carries the same method (ScikitBuildRedirectingFinder for redirect installs, ScikitBuildInplaceFinder for inplace):

import sys

finder = next(
    f
    for f in sys.meta_path
    if type(f).__name__ in {"ScikitBuildRedirectingFinder", "ScikitBuildInplaceFinder"}
)
finder.rebuild()

Added in version 1.0: Manual __loader__.rebuild() for redirect installs, and both manual and automatic (editable.rebuild) rebuilds for inplace installs.

Messages¶

You can add a message to be printed after a successful or failed build. For example:

[tool.scikit-build]
messages.after-success = "{green}Wheel successfully built"
messages.after-failure = """
{bold.red}Sorry{normal}, build failed. Your platform is {platform.platform}.
"""

This will be run through Python’s formatter, so escape curly brackets if you need them. Currently, there are several formatter-style keywords available: sys, platform (parenthesis will be added for items like platform.platform for you), __version__ for scikit-build-core’s version, and style keywords.

For styles, the colors are default, red, green, yellow, blue, magenta, cyan, and white. These can be accessed as fg.* or bg.*, without a qualifier the foreground is assumed. Styles like normal, bold, italic, underline, reverse are also provided. A full clearing of all styles is possible with reset. These all can be chained, as well, so bold.red.bg.blue is valid, and will produce an optimized escape code. Remember that you need to set the environment variable FORCE_COLOR to see colors with pip.

Added in version 0.10.

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. See Formattable fields.

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

The following features currently require this flag:

Wheel variants: PEP 817 variant support (variant, variant-name, variant-label, and null-variant), added in 1.0. See Building wheel variants (experimental).
Legacy tool.scikit-build.metadata plugins: dynamic metadata providers not shipped with scikit-build-core (anything using provider-path or a provider outside the scikit_build_core.* namespace) used through the deprecated tool.scikit-build.metadata table. The standard [[tool.dynamic-metadata]] interface supports the same providers without this flag. See Dynamic metadata.
Leading-slash wheel trees: the deprecated absolute spelling (/platlib, /data, /headers, /scripts, /metadata) for wheel.install-dir and wheel.force-include, placed one level above the platlib root. The ${SKBUILD_<TREE>_DIR} prefix is the non-experimental replacement. See wheel.install-dir.

The rebuild-on-import feature for editable installs is also considered experimental and subject to change, but is not gated behind this flag.

You can also fail the build with fail = true. This is useful with overrides if you want to make a specific configuration fail. If this is set, extra dependencies like "cmake" will not be requested.

Added in version 0.10.

Overrides¶

The overrides system allows you to customize for a wide variety of situations. It is described at Overrides.

Full Schema¶

You can see the full schema at Schema.

Configuration¶

Verbosity¶

Minimum version & defaults¶

CMake and Ninja minimum versions¶

Configuring source file inclusion¶

Customizing the built wheel¶

Force-including files¶

Building a wheel from an SDist¶

Customizing the output wheel¶

Configuring CMake arguments and defines¶

Environment variables for the build¶

Selecting a compiler¶

Search paths for dependencies¶

Editable installs¶

Triggering a rebuild manually¶

Messages¶

Other options¶

Overrides¶

Full Schema¶