{"id":1037,"library":"uv-build","title":"uv-build: The uv build backend","description":"uv-build is the official PEP 517 build backend for uv, the fast Python package and project manager. It enables uv to efficiently create source distributions and binary wheels for Python projects. The package is a slimmed-down version of uv itself, containing only the necessary components for the build backend functionality. It is under active development with frequent releases, often multiple times a week, ensuring tight integration and performance with the main uv tool.","status":"active","version":"0.11.2","language":"python","source_language":"en","source_url":"https://github.com/astral-sh/uv","tags":["build-backend","packaging","uv","rust-powered","fast","pep-517"],"install":[{"cmd":"pip install uv-build","lang":"bash","label":"Install uv-build"}],"dependencies":[{"reason":"uv-build is the build backend *for* uv. While not a direct runtime dependency in the traditional Python import sense, uv is the primary tool that orchestrates and uses uv-build for project building operations. uv-build's versioning policy follows uv's.","package":"uv","optional":false}],"imports":[{"note":"uv-build functions as a backend, not a library meant for direct programmatic imports by end-users. Its interaction is through the PEP 517 build system interface.","symbol":"uv-build as a backend","correct":"uv-build is a PEP 517 build backend and is not typically imported directly in user-facing Python code. It is invoked implicitly by build frontends like the `uv build` command or other packaging tools configured in `pyproject.toml`."}],"quickstart":{"code":"mkdir my_python_project\ncd my_python_project\n\n# Initialize a uv project (this creates pyproject.toml)\nuv init\n\n# Edit pyproject.toml to specify uv-build as the build backend\n# This content should be placed in pyproject.toml\n# --- pyproject.toml ---\n# [project]\n# name = \"my-package\"\n# version = \"0.1.0\"\n# dependencies = []\n#\n# [build-system]\n# requires = [\"uv-build>=0.11.2\"]\n# build-backend = \"uv_build\"\n# ---\n\n# Build your package (creates sdist and wheel in ./dist)\nuv build\n\n# Optionally, publish to a registry (e.g., TestPyPI)\n# uv publish --token $UV_PUBLISH_TOKEN --publish-url https://test.pypi.org/legacy/","lang":"bash","description":"To use `uv-build`, you typically configure it in your `pyproject.toml` file under the `[build-system]` section. This tells build tools like `uv` how to build your project. After configuration, you use the `uv build` command to create your package distributions. The example demonstrates setting up a basic project and explicitly configuring `uv-build` as the backend."},"warnings":[{"fix":"Ensure your environment's certificate stores are up-to-date, or investigate specific certificate issues if network requests begin failing.","message":"Version 0.11.0 included significant changes to uv's networking stack (driven by a `reqwest` upgrade to v0.13), which may rarely result in previously trusted SSL/TLS certificates being rejected. Exercise caution when upgrading in environments sensitive to network configurations.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"For projects with non-pure Python components, configure your `pyproject.toml` to use a different build backend (e.g., `hatchling.build_api` or `setuptools.build_meta`).","message":"The `uv-build` backend currently only supports pure Python code. If your project includes extension modules (e.g., written in C, C++, Rust), or requires a more flexible project layout with custom build scripts, you will need to use an alternative build backend like `hatchling` or `setuptools`.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `uv build --no-sources` before publishing your package to a public index to verify build integrity without local source overrides.","message":"When publishing packages, it is recommended to run `uv build --no-sources`. This ensures that the package builds correctly even when `tool.uv.sources` (custom dependency sources for development) are disabled, as is common with other build tools or in CI/CD environments.","severity":"gotcha","affected_versions":"All"},{"fix":"Treat `uv.lock` as a machine-generated file. Use `uv` CLI commands (`uv add`, `uv remove`, `uv lock --upgrade-package`) to manage dependencies, which will automatically update the lockfile.","message":"The `uv.lock` file, which pins exact dependency versions for reproducibility, should always be committed to version control and should *not* be manually edited. uv automatically manages this file.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure that any shell commands are executed in a shell environment (e.g., using `subprocess` module in Python, or by running directly in a terminal), and that `.py` files contain valid Python syntax.","message":"Attempting to execute shell commands directly as Python code will result in a `SyntaxError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure Python scripts only contain valid Python syntax. For executing shell commands, use Python's `subprocess` module (e.g., `subprocess.run(['mkdir', 'my_python_project'])`) or `os.system`.","message":"The test script encountered a Python `SyntaxError` by attempting to run a shell command (`mkdir`) directly as Python code, preventing the proper execution of `uv` commands.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T22:55:38.176Z","next_check":"2026-06-27T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.14","cli_name":"uv","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"18.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.1,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}