uv build

Build Python packages into source distributions (sdist) and wheels.

Usage

uv build [OPTIONS] [SRC]

Description

uv build accepts a path to a directory or source distribution, which defaults to the current working directory. By default, if passed a directory, uv build will build:

A source distribution (“sdist”) from the source directory
A binary distribution (“wheel”) from the source distribution

You can control the build outputs using --sdist and --wheel flags. If passed a source distribution, uv build --wheel will build a wheel from the source distribution.

Arguments

`[SRC]`

The directory from which distributions should be built, or a source distribution archive to build into a wheel. Defaults to the current working directory.

# Build from current directory
uv build

# Build from specific directory
uv build ./my-package

# Build wheel from source distribution
uv build --wheel dist/my-package-1.0.0.tar.gz

Options

Build output options

`--sdist`

Build only a source distribution from the given directory.

uv build --sdist

`--wheel`

Build only a binary distribution (wheel) from the given directory.

uv build --wheel

`--sdist --wheel`

Build both distributions from source.

uv build --sdist --wheel

Output directory

`-o, --out-dir <OUT_DIR>`

The output directory to which distributions should be written. Defaults to the dist subdirectory within the source directory, or the directory containing the source distribution archive.

uv build --out-dir ./build-output

Workspace options

`--package <PACKAGE>`

Build a specific package in the workspace. The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided. If the workspace member does not exist, uv will exit with an error.

uv build --package my-workspace-member

`--all-packages`

Build all packages in the workspace. The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.

uv build --all-packages

Alias: --all

Build constraints

`-c, --build-constraints <BUILD_CONSTRAINTS>`

Constrain build dependencies using the given requirements files when building distributions. Constraints files are requirements.txt-like files that only control the version of a build dependency that’s installed. However, including a package in a constraints file will not trigger the inclusion of that package on its own.

uv build --build-constraints constraints.txt

Environment variable: UV_BUILD_CONSTRAINT Alias: --build-constraint

Hash verification

`--require-hashes`

Require a matching hash for each build requirement. By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. When --require-hashes is enabled, all requirements must include a hash or set of hashes, and all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL. Hash-checking mode introduces additional constraints:

Git dependencies are not supported
Editable installations are not supported
Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory

uv build --require-hashes

Environment variable: UV_REQUIRE_HASHES

`--no-verify-hashes`

Disable validation of hashes in the requirements file. By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.

uv build --no-verify-hashes

Environment variable: UV_NO_VERIFY_HASHES

Build behavior

`--clear`

Clear the output directory before the build, removing stale artifacts.

uv build --clear

`--no-build-logs`

Hide logs from the build backend.

uv build --no-build-logs

`--force-pep517`

Always build through PEP 517, don’t use the fast path for the uv build backend. By default, uv won’t create a PEP 517 build environment for packages using the uv build backend, but use a fast path that calls into the build backend directly. This option forces always using PEP 517.

uv build --force-pep517

`--no-create-gitignore`

Do not create a .gitignore file in the output directory. By default, uv creates a .gitignore file in the output directory to exclude build artifacts from version control. When this flag is used, the file will be omitted.

uv build --no-create-gitignore

Python version

`-p, --python <PYTHON>`

The Python interpreter to use for the build environment. By default, builds are executed in isolated virtual environments. The discovered interpreter will be used to create those environments, and will be symlinked or copied in depending on the platform. See uv help python for details on Python discovery and supported request formats.

# Use specific Python version
uv build --python 3.12

# Use Python from specific path
uv build --python /usr/bin/python3.11

Environment variable: UV_PYTHON

Examples

Build both sdist and wheel

uv build

Output:

Building source distribution...
Building wheel from source distribution...
Successfully built dist/my-package-1.0.0.tar.gz and dist/my_package-1.0.0-py3-none-any.whl

Build only a wheel

uv build --wheel

Useful when you already have a source distribution and want to create a wheel.

Build only a source distribution

uv build --sdist

Useful for creating distributions for upload to PyPI.

Build with custom output directory

uv build --out-dir ./artifacts

Builds will be written to ./artifacts instead of the default dist directory.

Build a workspace package

uv build --package my-lib

When working in a workspace, build a specific member package.

Build all workspace packages

uv build --all-packages

Builds all packages in the workspace.

Build from a source distribution

uv build --wheel dist/my-package-1.0.0.tar.gz

Converts a source distribution to a wheel.

Clear previous builds

uv build --clear

Removes any existing files in the output directory before building.

Build with specific Python version

uv build --python 3.11

Uses Python 3.11 for the build environment.

Use cases

Preparing for publication

Build distributions before publishing to PyPI:

uv build
uv publish

CI/CD pipelines

Build and test distributions in continuous integration:

uv build --clear --out-dir ./dist
python -m pip install ./dist/*.whl
pytest

Local testing

Build and install locally for testing:

uv build --wheel
uv pip install dist/*.whl

Workspace management

Build specific packages in a monorepo:

uv build --package backend
uv build --package frontend

uv publish - Upload distributions to an index
uv pip install - Install packages from built wheels
uv init - Create a new project

Notes

By default, uv builds both a source distribution and a wheel
The build process uses PEP 517 build backends
For packages using the uv build backend, uv uses an optimized fast path unless --force-pep517 is specified
Build artifacts are written to the dist directory by default
Use --clear to ensure clean builds without stale artifacts

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​uv build

​Usage

​Description

​Arguments

​[SRC]

​Options

​Build output options

​--sdist

​--wheel

​--sdist --wheel

​Output directory

​-o, --out-dir <OUT_DIR>

​Workspace options

​--package <PACKAGE>

​--all-packages

​Build constraints

​-c, --build-constraints <BUILD_CONSTRAINTS>

​Hash verification

​--require-hashes

​--no-verify-hashes

​Build behavior

​--clear

​--no-build-logs

​--force-pep517

​--no-create-gitignore

​Python version

​-p, --python <PYTHON>

​Examples

​Build both sdist and wheel

​Build only a wheel

​Build only a source distribution

​Build with custom output directory

​Build a workspace package

​Build all workspace packages

​Build from a source distribution

​Clear previous builds

​Build with specific Python version

​Use cases

​Preparing for publication

​CI/CD pipelines

​Local testing

​Workspace management

​Related commands

​Notes

Build docs developers (and LLMs) love