Skip to content
Back to top

# Backend Configuration

The `--config-setting` (or `-C`) flag allows you to pass options to your build backend. The syntax and available options depend entirely on which backend you’re using (e.g., setuptools, hatchling, flit).

Important

The `--config-setting` flag passes options to the build backend that actually builds your package, not to build itself. Different backends accept different options. Check your backend’s documentation for available settings.

## Basic syntax

The basic syntax is:

    $ python -m build -C KEY=VALUE

Or for options without values:

    $ python -m build -C KEY=

Note

build also accepts the bare `-C KEY` form (without `=`) and reads it as `-C KEY=`, but warns you because pip rejects it. Write `-C KEY=` to keep the command working in both tools.

Multiple settings can be provided:

    $ python -m build -C KEY1=VALUE1 -C KEY2=VALUE2

## Setuptools

Setuptools requires a special `--build-option` wrapper for most settings.

### Build numbers

To add a build number to your wheel:

    $ python -m build --wheel \
        -C--build-option=bdist_wheel \
        -C--build-option=--build-number \
        -C--build-option=123

This creates a wheel named `package-1.0.0-123-py3-none-any.whl`.

### Compiler selection

To specify a compiler on Windows:

    $ python -m build \
        -C--build-option=build_ext \
        -C--build-option=--compiler \
        -C--build-option=mingw32

Note

Each argument must be a separate `-C` flag. Setuptools processes these as separate command-line arguments.

### Getting help

To see available setuptools build options:

    $ python -m build -C--build-option=--help

## scikit-build-core

scikit-build-core uses a more intuitive dotted syntax.

### CMake options

    $ python -m build \
        -Ccmake.define.BUILD_TESTING=OFF \
        -Ccmake.define.CMAKE_BUILD_TYPE=Release

### Logging

    $ python -m build -Clogging.level=INFO

### Install target

    $ python -m build -Cinstall.strip=false

Multiple options:

    $ python -m build \
        -Clogging.level=DEBUG \
        -Ccmake.define.USE_CUDA=ON \
        -Cinstall.components=runtime

## meson-python

Meson-python passes options directly to meson.

### Setup options

    $ python -m build -Csetup-args=-Doption=value

### Compile options

    $ python -m build \
        -Csetup-args=-Dbuildtype=release \
        -Csetup-args=-Db_ndebug=true

## hatchling

Hatchling supports various build options.

### Reproducible builds

    $ python -m build -Creproducible=true

### Shared data

    $ python -m build -Cshared-data=/custom/path

## flit-core

Flit-core has minimal configuration options as it focuses on simplicity.

## poetry-core

Poetry-core currently does not support configuration settings via the command line.

## Using `--config-json`

For complex nested configuration, use `--config-json` instead:

    $ python -m build --config-json='{"cmake": {"define": {"VAR1": "value1", "VAR2": "value2"}}}'

This is particularly useful in CI/CD scripts where configuration can be generated programmatically.

Note

`--config-setting` and `--config-json` cannot be used together.

## Common Issues

### Options starting with hyphens

If your option starts with a hyphen, you must use the `=` syntax to prevent build from interpreting it as its own flag:

    $ python -m build -C=--my-setting

Not `-C --my-setting` which would fail.

### Backend not recognizing options

If your backend doesn’t recognize an option:

1. Check your backend’s documentation for the correct syntax

2. Verify you’re using the latest version of the backend

3. Some backends only support certain options in newer versions

## Finding backend documentation

- Setuptools

- scikit-build-core

- meson-python

- hatchling

- flit-core

- poetry-core

- pdm-backend

## See also

- Basic Usage for general build commands

- Command-Line Interface for all command-line options

- Build Backends to understand how backends work