uv build: Build Wheels and Sdists
uv build creates a source distribution and a wheel for the project, writing them to dist/.
uv build is how you produce release artifacts from a uv project. It runs the configured build backend in an isolated environment, the way python -m build does, but faster.
What it does
uv build invokes the project build backend (defined in [build-system] of pyproject.toml) to produce an sdist (.tar.gz) and a wheel (.whl), placing both in dist/ by default. By default it builds the sdist first, then a wheel from that sdist.
Common usage
uv build
uv build --wheel
uv build --sdist
uv build --out-dir build-artifacts/
uv build path/to/packageOptions
| Flag | What it does |
|---|---|
| --wheel | Build only the wheel |
| --sdist | Build only the source distribution |
| --out-dir <dir> | Write artifacts somewhere other than dist/ |
| --no-build-isolation | Build in the current environment, no isolation |
| --package <name> | In a workspace, build a specific member |
In CI
Run uv build before uv publish in a release job, then upload dist/ as an artifact. Cache $UV_CACHE_DIR so build backends and their dependencies are not re-downloaded each run. Use --no-build-isolation only when you deliberately preinstalled the build deps.
Common errors in CI
"error: Failed to build <pkg>" wrapping "ModuleNotFoundError: No module named '<backend>'" means the build backend is missing and isolation was disabled; drop --no-build-isolation or install it. "Build backend failed to determine metadata" usually points at an invalid [build-system] table. A missing C compiler shows up as "error: command 'gcc' failed".