mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-12 15:55:02 +00:00
80d485d32a
We regularly get questions why `uv build` is missing certain files or using the wrong build tag, when that's done by the build backend and part of the build backend's docs. I tried to clarify this difference and to redirect users to look at the tool's docs instead of wondering why uv's docs don't explain that. --------- Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com> Co-authored-by: Zanie Blue <contact@zanie.dev>
59 lines
2.5 KiB
Markdown
59 lines
2.5 KiB
Markdown
# Building distributions
|
|
|
|
To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to
|
|
build it into a distributable format.
|
|
|
|
Python projects are typically distributed as both source distributions (sdists) and binary
|
|
distributions (wheels). The former is typically a `.tar.gz` or `.zip` file containing the project's
|
|
source code along with some additional metadata, while the latter is a `.whl` file containing
|
|
pre-built artifacts that can be installed directly.
|
|
|
|
!!! important
|
|
|
|
When using `uv build`, uv acts as a [build frontend](https://peps.python.org/pep-0517/#terminology-and-goals)
|
|
and only determines the Python version to use and invokes the build backend. The details of
|
|
the builds, such as the included files and the distribution filenames, are determined by the build
|
|
backend, as defined in [`[build-system]`](./config.md#build-systems). Information about build
|
|
configuration can be found in the respective tool's documentation.
|
|
|
|
## Using `uv build`
|
|
|
|
`uv build` can be used to build both source distributions and binary distributions for your project.
|
|
By default, `uv build` will build the project in the current directory, and place the built
|
|
artifacts in a `dist/` subdirectory:
|
|
|
|
```console
|
|
$ uv build
|
|
$ ls dist/
|
|
example-0.1.0-py3-none-any.whl
|
|
example-0.1.0.tar.gz
|
|
```
|
|
|
|
You can build the project in a different directory by providing a path to `uv build`, e.g.,
|
|
`uv build path/to/project`.
|
|
|
|
`uv build` will first build a source distribution, and then build a binary distribution (wheel) from
|
|
that source distribution.
|
|
|
|
You can limit `uv build` to building a source distribution with `uv build --sdist`, a binary
|
|
distribution with `uv build --wheel`, or build both distributions from source with
|
|
`uv build --sdist --wheel`.
|
|
|
|
## Build constraints
|
|
|
|
`uv build` accepts `--build-constraint`, which can be used to constrain the versions of any build
|
|
requirements during the build process. When coupled with `--require-hashes`, uv will enforce that
|
|
the requirement used to build the project match specific, known hashes, for reproducibility.
|
|
|
|
For example, given the following `constraints.txt`:
|
|
|
|
```text
|
|
setuptools==68.2.2 --hash=sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a
|
|
```
|
|
|
|
Running the following would build the project with the specified version of `setuptools`, and verify
|
|
that the downloaded `setuptools` distribution matches the specified hash:
|
|
|
|
```console
|
|
$ uv build --build-constraint constraints.txt --require-hashes
|
|
```
|