mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-10 06:45:00 +00:00

Some checks are pending
CI / cargo shear (push) Waiting to run
CI / build binary | freebsd (push) Blocked by required conditions
CI / ecosystem test | pydantic/pydantic-core (push) Blocked by required conditions
CI / ecosystem test | prefecthq/prefect (push) Blocked by required conditions
CI / ecosystem test | pallets/flask (push) Blocked by required conditions
CI / smoke test | linux (push) Blocked by required conditions
CI / check system | alpine (push) Blocked by required conditions
CI / smoke test | macos (push) Blocked by required conditions
CI / smoke test | windows x86_64 (push) Blocked by required conditions
CI / smoke test | windows aarch64 (push) Blocked by required conditions
CI / Determine changes (push) Waiting to run
CI / lint (push) Waiting to run
CI / build binary | windows aarch64 (push) Blocked by required conditions
CI / cargo clippy | ubuntu (push) Blocked by required conditions
CI / cargo clippy | windows (push) Blocked by required conditions
CI / cargo dev generate-all (push) Blocked by required conditions
CI / cargo test | ubuntu (push) Blocked by required conditions
CI / cargo test | macos (push) Blocked by required conditions
CI / cargo test | windows (push) Blocked by required conditions
CI / check windows trampoline | aarch64 (push) Blocked by required conditions
CI / check windows trampoline | i686 (push) Blocked by required conditions
CI / integration test | pypy on windows (push) Blocked by required conditions
CI / check windows trampoline | x86_64 (push) Blocked by required conditions
CI / test windows trampoline | i686 (push) Blocked by required conditions
CI / test windows trampoline | x86_64 (push) Blocked by required conditions
CI / typos (push) Waiting to run
CI / mkdocs (push) Waiting to run
CI / check system | python3.12 via chocolatey (push) Blocked by required conditions
CI / build binary | linux libc (push) Blocked by required conditions
CI / build binary | linux musl (push) Blocked by required conditions
CI / build binary | macos aarch64 (push) Blocked by required conditions
CI / build binary | macos x86_64 (push) Blocked by required conditions
CI / build binary | windows x86_64 (push) Blocked by required conditions
CI / cargo build (msrv) (push) Blocked by required conditions
CI / integration test | conda on ubuntu (push) Blocked by required conditions
CI / integration test | deadsnakes python3.9 on ubuntu (push) Blocked by required conditions
CI / integration test | free-threaded on windows (push) Blocked by required conditions
CI / integration test | pypy on ubuntu (push) Blocked by required conditions
CI / integration test | graalpy on ubuntu (push) Blocked by required conditions
CI / integration test | graalpy on windows (push) Blocked by required conditions
CI / integration test | pyodide on ubuntu (push) Blocked by required conditions
CI / integration test | github actions (push) Blocked by required conditions
CI / integration test | free-threaded python on github actions (push) Blocked by required conditions
CI / check cache | macos aarch64 (push) Blocked by required conditions
CI / integration test | determine publish changes (push) Blocked by required conditions
CI / integration test | registries (push) Blocked by required conditions
CI / integration test | uv publish (push) Blocked by required conditions
CI / integration test | uv_build (push) Blocked by required conditions
CI / check cache | ubuntu (push) Blocked by required conditions
CI / check system | python on debian (push) Blocked by required conditions
CI / check system | python on fedora (push) Blocked by required conditions
CI / check system | python on ubuntu (push) Blocked by required conditions
CI / check system | python on rocky linux 8 (push) Blocked by required conditions
CI / check system | python on rocky linux 9 (push) Blocked by required conditions
CI / check system | graalpy on ubuntu (push) Blocked by required conditions
CI / check system | pypy on ubuntu (push) Blocked by required conditions
CI / check system | pyston (push) Blocked by required conditions
CI / check system | python on macos aarch64 (push) Blocked by required conditions
CI / check system | homebrew python on macos aarch64 (push) Blocked by required conditions
CI / check system | python on macos x86-64 (push) Blocked by required conditions
CI / check system | python3.10 on windows x86-64 (push) Blocked by required conditions
CI / check system | python3.10 on windows x86 (push) Blocked by required conditions
CI / check system | python3.13 on windows x86-64 (push) Blocked by required conditions
CI / check system | x86-64 python3.13 on windows aarch64 (push) Blocked by required conditions
CI / check system | windows registry (push) Blocked by required conditions
CI / check system | python3.9 via pyenv (push) Blocked by required conditions
CI / check system | python3.13 (push) Blocked by required conditions
CI / check system | conda3.11 on macos aarch64 (push) Blocked by required conditions
CI / check system | conda3.8 on macos aarch64 (push) Blocked by required conditions
CI / check system | conda3.11 on linux x86-64 (push) Blocked by required conditions
CI / check system | conda3.8 on linux x86-64 (push) Blocked by required conditions
CI / check system | conda3.11 on windows x86-64 (push) Blocked by required conditions
CI / check system | conda3.8 on windows x86-64 (push) Blocked by required conditions
CI / check system | amazonlinux (push) Blocked by required conditions
CI / check system | embedded python3.10 on windows x86-64 (push) Blocked by required conditions
CI / benchmarks | walltime aarch64 linux (push) Blocked by required conditions
CI / benchmarks | instrumented (push) Blocked by required conditions
126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# The uv build backend
|
|
|
|
!!! note
|
|
|
|
The uv build backend is currently in preview and may change without warning.
|
|
|
|
When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend.
|
|
|
|
A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel.
|
|
While uv supports all build backends (as specified by PEP 517), it includes a `uv_build` backend
|
|
that integrates tightly with uv to improve performance and user experience.
|
|
|
|
The uv build backend currently only supports Python code. An alternative backend is required if you
|
|
want to create a
|
|
[library with extension modules](../concepts/projects/init.md#projects-with-extension-modules).
|
|
|
|
To use the uv build backend as [build system](../concepts/projects/config.md#build-systems) in an
|
|
existing project, add it to the `[build-system]` section in your `pyproject.toml`:
|
|
|
|
```toml
|
|
[build-system]
|
|
requires = ["uv_build>=0.7.15,<0.8.0"]
|
|
build-backend = "uv_build"
|
|
```
|
|
|
|
!!! important
|
|
|
|
The uv build backend follows the same [versioning policy](../reference/policies/versioning.md),
|
|
setting an upper bound on the `uv_build` version ensures that the package continues to build in
|
|
the future.
|
|
|
|
You can also create a new project that uses the uv build backend with `uv init`:
|
|
|
|
```shell
|
|
uv init --build-backend uv
|
|
```
|
|
|
|
`uv_build` is a separate package from uv, optimized for portability and small binary size. The `uv`
|
|
command includes a copy of the build backend, so when running `uv build`, the same version will be
|
|
used for the build backend as for the uv process. Other build frontends, such as `python -m build`,
|
|
will choose the latest compatible `uv_build` version.
|
|
|
|
## Modules
|
|
|
|
The default module name is the package name in lower case with dots and dashes replaced by
|
|
underscores, and the default module location is under the `src` directory, i.e., the build backend
|
|
expects to find `src/<package_name>/__init__.py`. These defaults can be changed with the
|
|
`module-name` and `module-root` setting. The example below expects a module in the project root with
|
|
`PIL/__init__.py` instead:
|
|
|
|
```toml
|
|
[tool.uv.build-backend]
|
|
module-name = "PIL"
|
|
module-root = ""
|
|
```
|
|
|
|
For a namespace packages, the path can be dotted. The example below expects to find a
|
|
`src/cloud/db/schema/__init__.py`:
|
|
|
|
```toml
|
|
[tool.uv.build-backend]
|
|
module-name = "cloud.db.schema"
|
|
```
|
|
|
|
Complex namespaces with more than one root module can be built by setting the `namespace` option,
|
|
which allows more than one root `__init__.py`:
|
|
|
|
```toml
|
|
[tool.uv.build-backend]
|
|
namespace = true
|
|
```
|
|
|
|
The build backend supports building stubs packages with a `-stubs` suffix on the package or module
|
|
name, including for namespace packages.
|
|
|
|
## Include and exclude configuration
|
|
|
|
To select which files to include in the source distribution, uv first adds the included files and
|
|
directories, then removes the excluded files and directories. This means that exclusions always take
|
|
precedence over inclusions.
|
|
|
|
When building the source distribution, the following files and directories are included:
|
|
|
|
- `pyproject.toml`
|
|
- The module under `tool.uv.build-backend.module-root`, by default
|
|
`src/<module-name or project_name_with_underscores>/**`.
|
|
- `project.license-files` and `project.readme`.
|
|
- All directories under `tool.uv.build-backend.data`.
|
|
- All patterns from `tool.uv.build-backend.source-include`.
|
|
|
|
From these, `tool.uv.build-backend.source-exclude` and the default excludes are removed.
|
|
|
|
When building the wheel, the following files and directories are included:
|
|
|
|
- The module under `tool.uv.build-backend.module-root`, by default
|
|
`src/<module-name or project_name_with_underscores>/**`.
|
|
- `project.license-files` and `project.readme`, as part of the project metadata.
|
|
- Each directory under `tool.uv.build-backend.data`, as data directories.
|
|
|
|
From these, `tool.uv.build-backend.source-exclude`, `tool.uv.build-backend.wheel-exclude` and the
|
|
default excludes are removed. The source dist excludes are applied to avoid source tree to wheel
|
|
source builds including more files than source tree to source distribution to wheel build.
|
|
|
|
There are no specific wheel includes. There must only be one top level module, and all data files
|
|
must either be under the module root or in the appropriate
|
|
[data directory](../reference/settings.md#build-backend_data). Most packages store small data in the
|
|
module root alongside the source code.
|
|
|
|
## Include and exclude syntax
|
|
|
|
Includes are anchored, which means that `pyproject.toml` includes only
|
|
`<project root>/pyproject.toml`. For example, `assets/**/sample.csv` includes all `sample.csv` files
|
|
in `<project root>/assets` or any child directory. To recursively include all files under a
|
|
directory, use a `/**` suffix, e.g. `src/**`.
|
|
|
|
!!! note
|
|
|
|
For performance and reproducibility, avoid patterns without an anchor such as `**/sample.csv`.
|
|
|
|
Excludes are not anchored, which means that `__pycache__` excludes all directories named
|
|
`__pycache__` and its children anywhere. To anchor a directory, use a `/` prefix, e.g., `/dist` will
|
|
exclude only `<project root>/dist`.
|
|
|
|
All fields accepting patterns use the reduced portable glob syntax from
|
|
[PEP 639](https://peps.python.org/pep-0639/#add-license-FILES-key), with the addition that
|
|
characters can be escaped with a backslash.
|