Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edits to the build backend documentation (#14376) 

Co-authored-by: konstin <konstin@mailbox.org>
This commit is contained in:
Zanie Blue 2025-07-01 03:44:23 -05:00 committed by GitHub
parent a3db9a9ae4
commit b1812d111a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 150 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
docs/concepts/build-backend.md
View File

@ -7,98 +7,188 @@
When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend. 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. 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 uv supports all build backends (as specified by [PEP 517](https://peps.python.org/pep-0517/)), but
want to create a also provides a native build backend (`uv_build`) that integrates tightly with uv to improve
[library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). performance and user experience.
To use the uv build backend as [build system](../concepts/projects/config.md#build-systems) in an ## Using the uv build backend
existing project, add it to the `[build-system]` section in your `pyproject.toml`:
```toml !!! important
The uv build backend currently **only supports pure Python code**. An alternative backend is to
build a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules).
To use uv as a build backend in an existing project, add `uv_build` to the
[`[build-system]`](../concepts/projects/config.md#build-systems) section in your `pyproject.toml`:
```toml title="pyproject.toml"
[build-system] [build-system]
requires = ["uv_build>=0.7.17,<0.8.0"] requires = ["uv_build>=0.7.17,<0.8.0"]
build-backend = "uv_build" build-backend = "uv_build"
``` ```
!!! important !!! note
The uv build backend follows the same [versioning policy](../reference/policies/versioning.md), 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 as uv. Including an upper bound on the `uv_build` version ensures that your package continues to
the future. build correctly as new versions are released.
You can also create a new project that uses the uv build backend with `uv init`: To create a new project that uses the uv build backend, use `uv init`:
```shell ```console
uv init --build-backend uv $ uv init --build-backend uv
``` ```
`uv_build` is a separate package from uv, optimized for portability and small binary size. The `uv` When the project is built, e.g., with [`uv build`](../guides/package.md), the uv build backend will
command includes a copy of the build backend, so when running `uv build`, the same version will be be used to create the source distribution and wheel.
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. ## Bundled build backend
The build backend is published as a separate package (`uv_build`) that is optimized for portability
and small binary size. However, the `uv` executable also includes a copy of the build backend, which
will be used during builds performed by uv, e.g., during `uv build`, if its version is compatible
with the `uv_build` requirement. If it's not compatible, a compatible version of the `uv_build`
package will be used. Other build frontends, such as `python -m build`, will always use the
`uv_build` package, typically choosing the latest compatible version.
## Modules ## Modules
The default module name is the package name in lower case with dots and dashes replaced by Python packages are expected to contain one or more Python modules, which are directories containing
underscores, and the default module location is under the `src` directory, i.e., the build backend an `__init__.py`. By default, a single root module is expected at `src/<package_name>/__init__.py`.
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 For example, the structure for a project named `foo` would be:
```text
pyproject.toml
src
└── foo
└── __init__.py
```
uv normalizes the package name to determine the default module name: the package name is lowercased
and dots and dashes are replaced with underscores, e.g., `Foo-Bar` would be converted to `foo_bar`.
The `src/` directory is the default directory for module discovery.
These defaults can be changed with the `module-name` and `module-root` settings. For example, to use
a `FOO` module in the root directory, as in the project structure:
```text
pyproject.toml
FOO
└── __init__.py
```
The correct build configuration would be:
```toml title="pyproject.toml"
[tool.uv.build-backend] [tool.uv.build-backend]
module-name = "PIL" module-name = "FOO"
module-root = "" module-root = ""
``` ```
For a namespace packages, the path can be dotted. The example below expects to find a ## Namespace packages
`src/cloud/db/schema/__init__.py`:
```toml Namespace packages are intended for use-cases where multiple packages write modules into a shared
[tool.uv.build-backend] namespace.
module-name = "cloud.db.schema"
Namespace package modules are identified by a `.` in the `module-name`. For example, to package the
module `bar` in the shared namespace `foo`, the project structure would be:
```text
pyproject.toml
src
└── foo
└── bar
└── __init__.py
``` ```
Complex namespaces with more than one root module can be built by setting the `namespace` option, And the `module-name` configuration would be:
which allows more than one root `__init__.py`:
```toml ```toml title="pyproject.toml"
[tool.uv.build-backend]
module-name = "foo.bar"
```
!!! important
The `__init__.py` file is not included in `foo`, since it's the shared namespace module.
It's also possible to have a complex namespace package with more than one root module, e.g., with
the project structure:
```text
pyproject.toml
src
├── foo
│   └── __init__.py
└── bar
└── __init__.py
```
While we do not recommend this structure (i.e., you should use a workspace with multiple packages
instead), it is supported via the `namespace` option:
```toml title="pyproject.toml"
[tool.uv.build-backend] [tool.uv.build-backend]
namespace = true namespace = true
``` ```
The build backend supports building stubs packages with a `-stubs` suffix on the package or module ## Stub packages
name, including for namespace packages.
## Include and exclude configuration The build backend also supports building type stub packages, which are identified by the `-stubs`
suffix on the package or module name, e.g., `foo-stubs`. The module name for type stub packages must
end in `-stubs`, so uv will not normalize the `-` to an underscore. Additionally, uv will search for
a `__init__.pyi` file. For example, the project structure would be:
To select which files to include in the source distribution, uv first adds the included files and ```text
pyproject.toml
src
└── foo-stubs
└── __init__.pyi
```
Type stub modules are also supported for [namespace packages](#namespace-packages).
## File inclusion and exclusion
The build backend is responsible for determining which files in a source tree should be packaged
into the distributions.
To determine which files to include in a source distribution, uv first adds the included files and
directories, then removes the excluded files and directories. This means that exclusions always take directories, then removes the excluded files and directories. This means that exclusions always take
precedence over inclusions. precedence over inclusions.
When building the source distribution, the following files and directories are included: By default, uv excludes `__pycache__`, `*.pyc`, and `*.pyo`.
- `pyproject.toml` When building a source distribution, 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`.
- 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. - The `pyproject.toml`
- The [module](#modules) under
[`tool.uv.build-backend.module-root`](../reference/settings.md#build-backend_module-root).
- The files referenced by `project.license-files` and `project.readme`.
- All directories under [`tool.uv.build-backend.data`](../reference/settings.md#build-backend_data).
- All files matching patterns from
[`tool.uv.build-backend.source-include`](../reference/settings.md#build-backend_source-include).
When building the wheel, the following files and directories are included: From these, items matching
[`tool.uv.build-backend.source-exclude`](../reference/settings.md#build-backend_source-exclude) and
the [default excludes](../reference/settings.md#build-backend_default-excludes) are removed.
- The module under `tool.uv.build-backend.module-root`, by default When building a wheel, the following files and directories are included:
`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 - The [module](#modules) under
default excludes are removed. The source dist excludes are applied to avoid source tree to wheel [`tool.uv.build-backend.module-root`](../reference/settings.md#build-backend_module-root)
- The files referenced by `project.license-files`, which are copied into the `.dist-info` directory.
- The `project.readme`, which is copied into the project metadata.
- All directories under [`tool.uv.build-backend.data`](../reference/settings.md#build-backend_data),
which are copied into the `.data` directory.
From these,
[`tool.uv.build-backend.source-exclude`](../reference/settings.md#build-backend_source-exclude),
[`tool.uv.build-backend.wheel-exclude`](../reference/settings.md#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. 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 There are no specific wheel includes. There must only be one top level module, and all data files
@ -106,20 +196,20 @@ 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 [data directory](../reference/settings.md#build-backend_data). Most packages store small data in the
module root alongside the source code. module root alongside the source code.
## Include and exclude syntax ### Include and exclude syntax
Includes are anchored, which means that `pyproject.toml` includes only Includes are anchored, which means that `pyproject.toml` includes only `<root>/pyproject.toml` and
`<project root>/pyproject.toml`. For example, `assets/**/sample.csv` includes all `sample.csv` files not `<root>/bar/pyproject.toml`. To recursively include all files under a directory, use a `/**`
in `<project root>/assets` or any child directory. To recursively include all files under a suffix, e.g. `src/**`. Recursive inclusions are also anchored, e.g., `assets/**/sample.csv` includes
directory, use a `/**` suffix, e.g. `src/**`. all `sample.csv` files in `<root>/assets` or any of its children.
!!! note !!! note
For performance and reproducibility, avoid patterns without an anchor such as `**/sample.csv`. 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 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 `__pycache__` regardless of its parent directory. All children of an exclusion are excluded as well.
exclude only `<project root>/dist`. To anchor a directory, use a `/` prefix, e.g., `/dist` will exclude only `<root>/dist`.
All fields accepting patterns use the reduced portable glob syntax from 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 [PEP 639](https://peps.python.org/pep-0639/#add-license-FILES-key), with the addition that