Skip to content
Back to top
View this page

# build

A simple, correct Python packaging build frontend.

build manages `pyproject.toml`-based builds, invoking build-backend hooks as appropriate to build a distribution package. It is a simple build tool and does not perform any dependency management.

## python -m build

        A simple, correct Python build frontend.

        By default, a source distribution (sdist) is built from the project root
        and a binary distribution (wheel) is built from the sdist.
        If this is undesirable, you can pass `--sdist` and/or `--wheel`
        to build distributions independently of each other.

    python -m build [-h] [--version] [--quiet | --verbose] [--outdir PATH] [--sdist] [--wheel]
                    [--metadata] [--config-setting KEY[=VALUE] | --config-json JSON_STRING]
                    [--installer {pip,uv} | --no-isolation] [--skip-dependency-check]
                    [srcdir]

### python -m build positional arguments

- `srcdir` - source directory (defaults to the current working directory)

### python -m build global options

- `-h`, `--help` - show this help message and exit

- `--version`, `-V` - show program’s version number and exit

- `--quiet`, `-q` - reduce verbosity (default: `0`)

- `--verbose`, `-v` - increase verbosity (default: `0`)

### python -m build build options

- `--outdir` `PATH`, `-o` `PATH` - output directory (defaults to `{srcdir}`/dist). Cannot be used together with `--metadata`

- `--sdist`, `-s` - build a source distribution (disables the default behavior)

- `--wheel`, `-w` - build a wheel (disables the default behavior)

- `--metadata` - print out a wheel’s metadata in JSON format. Cannot be used in conjunction with `--sdist` or `--wheel`

- `--config-setting` `KEY[=VALUE]`, `-C` `KEY[=VALUE]` - settings to pass to the backend. Multiple settings can be provided. Settings beginning with a hyphen will erroneously be interpreted as options to build if separated by a space; use `--config-setting=--my-setting -C--my-other-setting` instead (default: `None`)

- `--config-json` `JSON_STRING` - settings to pass to the backend as a JSON object. This is an alternative to `--config-setting` that allows complex nested structures. Cannot be used together with `--config-setting` (default: `None`)

### python -m build installation options

- `--installer` `INSTALLER` - Python package installer to use (defaults to pip)

- `--no-isolation`, `-n` - disable building the project in an isolated virtual environment. Build dependencies must be installed separately when this option is used

- `--skip-dependency-check`, `-x` - do not check that build dependencies are installed

Note

A `pyproject-build` CLI script is also available, so that tools such as pipx can use it.

By default build will build the package in an isolated environment, but this behavior can be disabled with `--no-isolation`.