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 positional arguments

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

python -m 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 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 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.