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.