> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv build

> Build Python packages into source distributions and wheels

# uv build

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

## Usage

```bash theme={null}
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:

1. A source distribution ("sdist") from the source directory
2. 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.

```bash theme={null}
# 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.

```bash theme={null}
uv build --sdist
```

#### `--wheel`

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

```bash theme={null}
uv build --wheel
```

#### `--sdist --wheel`

Build both distributions from source.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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`.

```bash theme={null}
uv build --no-verify-hashes
```

Environment variable: `UV_NO_VERIFY_HASHES`

### Build behavior

#### `--clear`

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

```bash theme={null}
uv build --clear
```

#### `--no-build-logs`

Hide logs from the build backend.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
uv build --wheel
```

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

### Build only a source distribution

```bash theme={null}
uv build --sdist
```

Useful for creating distributions for upload to PyPI.

### Build with custom output directory

```bash theme={null}
uv build --out-dir ./artifacts
```

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

### Build a workspace package

```bash theme={null}
uv build --package my-lib
```

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

### Build all workspace packages

```bash theme={null}
uv build --all-packages
```

Builds all packages in the workspace.

### Build from a source distribution

```bash theme={null}
uv build --wheel dist/my-package-1.0.0.tar.gz
```

Converts a source distribution to a wheel.

### Clear previous builds

```bash theme={null}
uv build --clear
```

Removes any existing files in the output directory before building.

### Build with specific Python version

```bash theme={null}
uv build --python 3.11
```

Uses Python 3.11 for the build environment.

## Use cases

### Preparing for publication

Build distributions before publishing to PyPI:

```bash theme={null}
uv build
uv publish
```

### CI/CD pipelines

Build and test distributions in continuous integration:

```bash theme={null}
uv build --clear --out-dir ./dist
python -m pip install ./dist/*.whl
pytest
```

### Local testing

Build and install locally for testing:

```bash theme={null}
uv build --wheel
uv pip install dist/*.whl
```

### Workspace management

Build specific packages in a monorepo:

```bash theme={null}
uv build --package backend
uv build --package frontend
```

## Related commands

* [`uv publish`](/cli/publish) - Upload distributions to an index
* [`uv pip install`](/cli/pip-install) - Install packages from built wheels
* [`uv init`](/cli/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