Skip to content

Commit 4ca3452

Browse files
committed
Clarify build dependency hash documentation
1 parent c922673 commit 4ca3452

5 files changed

Lines changed: 50 additions & 72 deletions

File tree

‎crates/uv-settings/src/settings.rs‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1086,14 +1086,14 @@ pub struct ResolverInstallerSchema {
10861086

10871087
/// Require hashes for all build dependencies.
10881088
///
1089-
/// Hashes in `build-constraint-dependencies` are checked when downloading build dependencies.
1090-
/// Enable this option to reject build dependencies without hashes. Hashes in URL fragments in
1091-
/// `build-system.requires` also count, but hashes returned by a build backend do not.
1092-
///
1093-
/// No hash is required when uv uses its bundled `uv_build` backend, since it is part of the uv
1094-
/// executable. When build isolation is disabled, build dependencies must already be installed
1095-
/// and their hashes are not checked. Already-installed packages and previously built wheels
1096-
/// are not checked.
1089+
/// uv checks hashes provided in `build-constraint-dependencies` when downloading build
1090+
/// dependencies. Enable this setting to require a hash for every build dependency, including
1091+
/// transitive dependencies. You can also provide hashes as URL fragments in
1092+
/// `build-system.requires`. Hashes returned by a build backend do not count.
1093+
///
1094+
/// Hashes are not required for the `uv_build` backend bundled in uv. When build isolation is
1095+
/// disabled, build dependencies must already be installed and their hashes are not checked.
1096+
/// Already-installed packages and previously built wheels are not checked.
10971097
///
10981098
/// This setting also applies to `uv pip` commands, where it can be overridden in `[tool.uv.pip]`.
10991099
#[option(

‎docs/concepts/projects/build.md‎

Lines changed: 20 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -58,11 +58,14 @@ that the downloaded `setuptools` distribution matches the specified hash:
5858
$ uv build --build-constraint constraints.txt --require-hashes
5959
```
6060

61+
To require hashes for every build dependency, including transitive dependencies, use
62+
`--require-build-hashes` instead.
63+
6164
### Project build dependency hashes
6265

63-
Projects can also specify build constraints in
64-
[`build-constraint-dependencies`](../../reference/settings.md#build-constraint-dependencies). To
65-
verify a downloaded build dependency, provide its `requirement` and `hashes` in a table:
66+
For example, to verify build dependencies during project resolution and installation, add hashes to
67+
[`build-constraint-dependencies`](../../reference/settings.md#build-constraint-dependencies) in your
68+
workspace's `pyproject.toml`:
6669

6770
```toml
6871
[tool.uv]
@@ -72,43 +75,24 @@ build-constraint-dependencies = [
7275
]
7376
```
7477

75-
An entry without hashes can be written as a string, as shown with `wheel<1` above. uv checks the
76-
supplied hashes when it downloads pinned build dependencies during project resolution or
77-
installation, including builds in `uv run --with` environments. These hashes apply to build
78-
dependencies. Packages installed in the project environment are verified against their own lockfile
79-
hashes.
80-
81-
To require hashes for **every** build dependency, use `--require-build-hashes` on supported
82-
commands, including those that may build packages while updating a lockfile. You can also set
83-
`UV_REQUIRE_BUILD_HASHES=true` or configure the workspace root:
84-
85-
```toml
86-
[tool.uv]
87-
require-build-hashes = true
88-
```
89-
90-
This option is experimental. Enable `--preview-features build-dependency-hashes` to suppress the
91-
warning.
78+
uv checks supplied hashes when it downloads pinned build dependencies. Constraints without hashes,
79+
such as `wheel<1`, are also allowed. To require a hash for every build dependency, including
80+
transitive dependencies, set
81+
[`require-build-hashes = true`](../../reference/settings.md#require-build-hashes) under `[tool.uv]`
82+
or pass `--require-build-hashes`.
9283

93-
Command-line flags take precedence over the environment variable, which takes precedence over
94-
configuration. `--no-require-build-hashes` and `UV_REQUIRE_BUILD_HASHES=false` allow build
95-
dependencies without hashes; provided hashes are still checked. Workspace members cannot override
96-
the root's configuration. For `uv pip` commands, use `[tool.uv.pip] require-build-hashes = false` to
97-
opt out of the top-level setting.
84+
You'll need to pin each build dependency to an exact version (or use a direct URL) and provide a
85+
hash. Hashes can also come from URL fragments in `build-system.requires`, but not from requirements
86+
returned by a build backend.
9887

99-
With `--require-build-hashes`, provide exact versions or direct URLs and hashes for all build
100-
dependencies, including their dependencies. Hashes can also come from URL fragments (e.g.,
101-
`#sha256=...`) in `build-system.requires`. Hashes in requirements or metadata returned by a build
102-
backend, such as through `get_requires_for_build_wheel`, do not count: those dependencies need
103-
hashes from build constraints or `build-system.requires`. Requirements whose environment markers do
104-
not match the current environment are ignored.
88+
When build isolation is disabled, uv uses the installed build dependencies without checking their
89+
hashes. uv also does not recheck already-installed packages or previously built wheels. The bundled
90+
`uv_build` backend does not need a hash because it is part of the uv executable.
10591

106-
When uv uses its bundled `uv_build` backend, no hash is required for it: the backend is part of the
107-
uv executable, not a separately downloaded package.
92+
!!! note
10893

109-
When build isolation is disabled with `--no-build-isolation` or `--no-build-isolation-package`,
110-
build dependencies must already be installed and their hashes are not checked. Already-installed
111-
packages and previously built wheels are not checked.
94+
`--require-build-hashes` is experimental. Use `--preview-features build-dependency-hashes` to
95+
suppress the warning.
11296

11397
## Preventing publish to PyPI
11498

‎docs/pip/compatibility.md‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -421,28 +421,6 @@ not when provided via `--constraint` on the command line.
421421
For example, to ensure that `setuptools 60.0.0` is used to build any packages with a build
422422
dependency on `setuptools`, use `--build-constraint`, rather than `--constraint`.
423423

424-
To require hashes for every build dependency, use `--require-build-hashes` with `uv pip install`,
425-
`uv pip sync`, or `uv pip compile`. Provide requirements with exact versions or direct URLs and
426-
`--hash` entries in the build constraints file:
427-
428-
```console
429-
$ uv pip install -r requirements.txt --build-constraint build-constraints.txt --require-build-hashes
430-
```
431-
432-
This option is experimental. Enable `--preview-features build-dependency-hashes` to suppress the
433-
warning. No hash is required when uv uses its bundled `uv_build` backend, since it is part of the uv
434-
executable. When build isolation is disabled with `--no-build-isolation` or
435-
`--no-build-isolation-package`, build dependencies must already be installed and their hashes are
436-
not checked. This option does not require hashes for runtime dependencies; use `--require-hashes`
437-
for those.
438-
439-
Set `UV_REQUIRE_BUILD_HASHES=true` to require build hashes across project, build, tool, and pip
440-
commands, including `uv pip compile`. Set it to `false` to disable the requirement, or pass
441-
`--no-require-build-hashes` to override it for `uv pip install`, `uv pip sync`, or `uv pip compile`.
442-
The top-level `[tool.uv] require-build-hashes` setting also applies to pip commands; set
443-
`[tool.uv.pip] require-build-hashes = false` to opt out for pip commands only. Command-line flags
444-
take precedence over the environment variable, which takes precedence over configuration.
445-
446424
## `pip compile` defaults
447425

448426
There are a few small but notable differences in the default behaviors of `pip compile` and

‎docs/pip/compile.md‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -162,11 +162,11 @@ append them to those specified in the constraints file.
162162
Similar to `constraints`, but specifically for build-time dependencies, including those required
163163
when building runtime dependencies.
164164

165-
Build constraint files are `requirements.txt`-like files that only control the _version_ of a
166-
build-time requirement. However, including a package in a build constraints file will _not_ trigger
167-
its installation at build time; instead, constraints apply only when the package is required as a
168-
direct or transitive build-time dependency. Build constraints can be used to add bounds to
169-
dependencies that are not explicitly declared as build-time dependencies of the current project.
165+
Build constraint files are `requirements.txt`-like files that constrain build-time requirements.
166+
However, including a package in a build constraints file will _not_ trigger its installation at
167+
build time; instead, constraints apply only when the package is required as a direct or transitive
168+
build-time dependency. Build constraints can be used to add bounds to dependencies that are not
169+
explicitly declared as build-time dependencies of the current project.
170170

171171
For example, if a package defines its build dependencies as follows:
172172

@@ -186,6 +186,22 @@ setuptools==75.0.0
186186
uv will also read `build-constraint-dependencies` from the `pyproject.toml` at the workspace root,
187187
and append them to those specified in the build constraints file.
188188

189+
To require hashes for build dependencies, add them to a build constraints file:
190+
191+
```requirements title="build-constraints.txt"
192+
setuptools==83.0.0 --hash=sha256:29b23c360f22f414dc7336bb39178cc7bcbf6021ed2733cde173f09dba19abb3
193+
```
194+
195+
Then pass the file with `--require-build-hashes`:
196+
197+
```console
198+
$ uv pip compile requirements.in --build-constraint build-constraints.txt --require-build-hashes
199+
```
200+
201+
This option only applies to build dependencies. To check runtime dependencies with `uv pip install`
202+
or `uv pip sync`, use `--require-hashes`. For details and limitations, see
203+
[project build dependency hashes](../concepts/projects/build.md#project-build-dependency-hashes).
204+
189205
## Overriding dependency versions
190206

191207
Overrides files are `requirements.txt`-like files that force a specific version of a requirement to

‎uv.schema.json‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)
⌂ 换网址