Skip to content
Back to top

# Command-Line Interface

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

        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]
                    [--dependency-constraints-txt PATH] [--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

- `--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`

### 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

- `--dependency-constraints-txt` `PATH` - constrain build dependencies using a constraints.txt when installing dependencies

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

## Isolation Behavior

By default build will build the package in an isolated environment, but this behavior can be disabled with `--no-isolation`. When using isolation, build creates a temporary virtual environment, installs the build dependencies specified in your `pyproject.toml`, runs the build, and then cleans up the environment. This ensures reproducible builds regardless of what packages are installed in your development environment.

## Alternative CLI Script

A `pyproject-build` CLI script is also available, which is functionally identical to `python -m build`. This is useful for tools like pipx that prefer direct script entry points.

    $ pyproject-build
    $ pyproject-build --help

Both commands accept the same options and behave identically.

## Common Patterns

For practical usage examples and workflows, see Basic Usage.

## See Also

- Basic Usage for common workflows

- Backend Configuration for passing options to backends

- Environment Variables for environment variables that affect build