uv-build

Build a package in the current directory

$ uv build

$ uv build [path/to/directory]

$ uv build --wheel

$ uv build --sdist

$ uv build [[-o|--out-dir]] [path/to/output]

$ uv build --package [package_name]

$ uv build [[--all|--all-packages]]

$ uv build [[-p|--python]] [python3.11]

uv build [OPTIONS] [PATH]

PATH
    The path to the project directory containing a pyproject.toml or setup.py file. Defaults to the current directory if not specified.

--sdist
    Builds a source distribution (.tar.gz file) of the project.

--wheel
    Builds a wheel (.whl file) of the project.

--output-dir DIR
    Directory where the built packages will be placed. Defaults to ./dist.

--no-build-isolation
    Disable build isolation. The build backend will be invoked in the current environment instead of an isolated one.

--no-clean
    Do not clean up the temporary build directory after building.

--config-setting KEY=VALUE
    Pass a configuration setting to the build backend (e.g., --config-setting="--build-option=--my-flag").

--python PYTHON_VERSION_OR_PATH
    Specify the Python interpreter to use for the build environment (e.g., 3.10, python3, or a full path).

--index-url URL
    Base URL of the Python Package Index (default: https://pypi.org/simple).

--extra-index-url URL
    Additional URL of a Python Package Index to use for package lookup.

--find-links PATH_OR_URL
    Look for packages in local directories or on given URLs. Supports directory paths and file://, http://, https:// URLs.

--verbose
    Enable verbose output, showing more details about the build process.

--quiet
    Suppress all output except for errors.

--offline
    Operate in offline mode, refusing to make network requests.

--cache-dir DIR
    Specify the directory for uv's cache.

--no-cache
    Disable uv's caching mechanism.

--strict
    Enable strict mode, treating warnings as errors.

The uv build command, part of the uv Python package manager, is designed for efficiently building Python source distributions (sdists) and wheels (wheels) from a local project directory. It serves as a fast, modern alternative to traditional Python packaging tools like pip build or directly invoking setup.py bdist_wheel.

uv build leverages uv's Rust-based performance and robust dependency resolution capabilities to ensure quick and reliable builds. It automatically detects the project's build backend (e.g., setuptools, hatch, flit) and invokes it within an isolated environment by default, preventing conflicts with the host system's Python environment. Users can specify whether to build an sdist, a wheel, or both, and control output directories and various build-time configurations, making it a versatile tool for packaging Python projects for distribution or deployment.

uv build is a powerful and fast tool, but it's important to be aware of its nuances:

1. Build Backend Compatibility: While uv aims for broad compatibility, ensure your project's build backend (setuptools, hatch, flit, etc.) is correctly configured in pyproject.toml.
2. Isolated Builds: By default, uv build uses isolated build environments. If your build process relies on specific system-level dependencies or environment variables, you might need to adjust them or use --no-build-isolation (though generally not recommended).
3. Maturity: uv is a relatively new project, and while stable for many use cases, it might still be actively developing new features or refining existing ones. Always refer to the official uv documentation for the latest best practices and any breaking changes.

By default, uv build creates a temporary isolated environment to install build-time dependencies (specified in build-system.requires in pyproject.toml). This prevents interference with your global or project-specific Python environment and ensures reproducible builds. If you need to disable this for specific reasons (e.g., complex native dependencies that cannot be easily isolated), use the --no-build-isolation flag.

Built packages (sdist and wheel) are, by default, placed in a dist/ directory located in your project's root. You can customize this output location using the --output-dir option, providing a path to an existing or new directory where the build artifacts should be saved.

The uv project, including its build functionality, was developed by Astral, a company founded by Charlie Marsh. It emerged in late 2023 as a high-performance, Rust-based alternative to existing Python packaging tools like pip and venv. The motivation behind uv was to drastically improve the speed and reliability of Python dependency management and project setup. The build command specifically addresses the need for a fast, robust way to create distributable Python packages, integrating seamlessly with uv's resolver and installer to handle build-time dependencies efficiently. Its development represents a significant step towards modernizing and accelerating the Python packaging ecosystem.

uv(1), pip(1), venv(1), python(1)