scikit-build-core

[!NOTE]

We have a public Scikit-build community meeting every month! Join us on Google Meet on the third Friday of every month at 12:00 PM ET. Some of our past meeting minutes are available here.

Scikit-build-core is a build backend for Python that uses CMake to build extension modules. It has a simple yet powerful static configuration system in pyproject.toml, and supports almost unlimited flexibility via CMake. It was initially developed to support the demanding needs of scientific users, but can build any sort of package that uses CMake.

Scikit-build-core is a ground-up rewrite of the classic Scikit-build. The key features of scikit-build classic (which is setuptools based) are also present here:

• Great support for or by most OSs, compilers, IDEs, and libraries
• Support for C++ features and other languages like Fortran
• Support for multithreaded builds
• Simple CMakeLists.txt files instead of up to thousands of lines of fragile setuptools/distutils code
• Cross-compile support for Apple Silicon and Windows ARM

Scikit-build-core was built using Python packaging standards developed after scikit-build (classic) was written. Using it directly provides the following features over classic Scikit-build:

• Better warnings, errors, and logging
• No warning about unused variables
• Automatically adds Ninja and/or CMake only as required
• No dependency on setuptools, distutils, or wheel
• Powerful config system, including config options support
• Automatic inclusion of site-packages in CMAKE_PREFIX_PATH
• FindPython is backported if running on CMake < 3.26.1 (configurable), supports PyPy SOABI & Limited API / Stable ABI
• Limited API / Stable ABI and pythonless tags supported via config option
• No slow generator search, ninja/make or MSVC used by default, respects CMAKE_GENERATOR
• SDists are reproducible by default (UNIX, Python 3.9+, uncompressed comparison recommended), and wheels can be made reproducible too (opt-in)
• Support for caching between builds (opt-in by setting build-dir)
• Support for writing out to extra wheel folders (scripts, headers, data)
• Support for selecting install components and build targets
• Dedicated entrypoints for module and prefix directories
• Several integrated dynamic metadata plugins, supporting the cross-backend [[tool.dynamic-metadata]] standard
• Editable mode support, with optional experimental auto rebuilds on import and optional in-place mode
• Supports WebAssembly (Emscripten/Pyodide).
• Supports free-threaded Python 3.13+, including the free-threaded stable ABI (PEP 803).
• A scikit-build CLI, including scikit-build init to scaffold a new project.

Current requirements:

• The minimum supported CMake is 3.15
• The minimum supported Python is 3.9 (3.8+ for 1.0.x and older)

The recommended interface is the native pyproject builder. Other backends are also available:

• Setuptools integration (use the [setuptools] extra)
• Hatchling plugin (use the [hatchling] extra)

[!WARNING]

The setuptools and hatchling backends might move to standalone packages in the future, so depend on them via the scikit-build-core[setuptools] and scikit-build-core[hatchling] extras to stay protected if they do.

Example

The fastest way to start a new project is scikit-build init (available via uvx scikit-build-core init as well), which generates a minimal CMake + scikit-build-core starter project. The pieces are described below.

To use scikit-build-core, add it to your build-system.requires, and specify the scikit_build_core.build builder as your build-system.build-backend. You do not need to specify cmake or ninja; scikit-build-core will require them automatically if the system versions are not sufficient.

[build-system]
requires = ["scikit-build-core"]
build-backend = "scikit_build_core.build"

[project]
name = "scikit_build_simplest"
version = "0.0.1"

You can (and should) specify the rest of the entries in project, but these are the minimum to get started.

An example CMakeLists.txt:

cmake_minimum_required(VERSION 3.15...4.4)
project(scikit_build_simplest LANGUAGES C)

find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)

Python_add_library(_module MODULE src/module.c WITH_SOABI)
install(TARGETS _module DESTINATION scikit_build_simplest)

The install(DESTINATION ...) is relative to site-packages, so the _module extension above lands at scikit_build_simplest/_module.* when the package is pip installed. Scikit-build-core will backport FindPython from CMake 3.26.1 to older versions of Python, and will handle PyPy for you if you are building from PyPy. You will need to install everything you want into the full final path inside site-packages (so you will usually prefix everything by the package name) -- including any __init__.py, which CMake can place alongside the extension with install(FILES src/__init__.py DESTINATION scikit_build_simplest).

The most important optional configuration is this:

[build-system]
requires = ["scikit-build-core>=1.0"]
build-backend = "scikit_build_core.build"

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

This will enable scikit-build-core to read your minimum requirement on itself and stay in compatibility mode for that version; if we make changes to defaults in the future, your package will continue to build exactly the same.

The Getting started guide walks through a complete package step by step. More examples are in the tests/packages.

Configuration

All configuration options can be placed in pyproject.toml, passed via -C in pip, uv, and build, or set as environment variables. tool.scikit-build is used in toml, skbuild. for -C options, or SKBUILD_* for environment variables.

For a full reference and explanation of the variables see the online documentation

A quick summary and some defaults are listed below:

Top-level

cmake

ninja

logging

sdist

wheel

backport

editable

build

install

generate[]

messages

search

Most CMake environment variables should be supported, and CMAKE_ARGS can be used to set extra CMake args. ARCHFLAGS is used to specify macOS universal2 or cross-compiles, just like setuptools.

You can also specify [[tool.scikit-build.overrides]] to customize values for different systems. See the docs for details.

Other projects for building

Scikit-build-core is a binary build backend. There are also other binary build backends:

• py-build-cmake: A different attempt at a standards compliant builder for CMake. Strong focus on cross-compilation. Uses Flit internals.
• cmeel: A different attempt at a standards compliant builder for CMake. Focus on building an ecosystem around a special unimportable folder in site-packages (similar to scikit-build's usage of cmake.* entrypoints, but folder-based).
• meson-python: A meson-based build backend; has some maintainer overlap with scikit-build-core.
• maturin: A build backend for Rust projects, using Cargo.
• enscons: A SCons based backend, not very actively developed (but it predates all the others in modern standard support!)

If you don't need a binary build, you don't need to use a binary build backend! There are some very good Python build backends; we recommend hatchling as a good balance between good defaults for beginners and good support for advanced use cases. This is the tool scikit-build-core itself uses.

Acknowledgements

Support for this work was provided by NSF grant OAC-2209877. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.