mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-11-19 11:35:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Enable first-class dependency exclusions (#16528)

Browse source 
## Summary

This PR adds an `exclude-dependencies` setting that allows users to omit
a dependency during resolution. It's effectively a formalized version of
the `flask ; python_version < '0'` hack that we've suggested to users in
various issues.

Closes #12616.
This commit is contained in:
Charlie Marsh 2025-10-31 10:14:12 -04:00 • committed by GitHub
parent 7978122837
commit 5c71b5c124
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
42 changed files with 711 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/reference/cli.md
View file

@ -2613,7 +2613,9 @@ uv tool install [OPTIONS] <PACKAGE>
<p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p></dd><dt id="uv-tool-install--exclude-newer-package"><a href="#uv-tool-install--exclude-newer-package"><code>--exclude-newer-package</code></a> <i>exclude-newer-package</i></dt><dd><p>Limit candidate packages for specific packages to those that were uploaded prior to the given date.</p>
<p>Accepts package-date pairs in the format <code>PACKAGE=DATE</code>, where <code>DATE</code> is an RFC 3339 timestamp (e.g., <code>2006-12-02T02:07:43Z</code>) or local date (e.g., <code>2006-12-02</code>) in your system's configured time zone.</p>
<p>Can be provided multiple times for different packages.</p>
</dd><dt id="uv-tool-install--extra-index-url"><a href="#uv-tool-install--extra-index-url"><code>--extra-index-url</code></a> <i>extra-index-url</i></dt><dd><p>(Deprecated: use <code>--index</code> instead) Extra URLs of package indexes to use, in addition to <code>--index-url</code>.</p>
</dd><dt id="uv-tool-install--excludes"><a href="#uv-tool-install--excludes"><code>--excludes</code></a>, <code>--exclude</code> <i>excludes</i></dt><dd><p>Exclude packages from resolution using the given requirements files.</p>
<p>Excludes files are <code>requirements.txt</code>-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.</p>
<p>May also be set with the <code>UV_EXCLUDE</code> environment variable.</p></dd><dt id="uv-tool-install--extra-index-url"><a href="#uv-tool-install--extra-index-url"><code>--extra-index-url</code></a> <i>extra-index-url</i></dt><dd><p>(Deprecated: use <code>--index</code> instead) Extra URLs of package indexes to use, in addition to <code>--index-url</code>.</p>
<p>Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.</p>
<p>All indexes provided via this flag take priority over the index specified by <code>--index-url</code> (which defaults to PyPI). When multiple <code>--extra-index-url</code> flags are provided, earlier values take priority.</p>
<p>May also be set with the <code>UV_EXTRA_INDEX_URL</code> environment variable.</p></dd><dt id="uv-tool-install--find-links"><a href="#uv-tool-install--find-links"><code>--find-links</code></a>, <code>-f</code> <i>find-links</i></dt><dd><p>Locations to search for candidate distributions, in addition to those found in the registry indexes.</p>
@ -4054,7 +4056,9 @@ uv pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>
<p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p></dd><dt id="uv-pip-compile--exclude-newer-package"><a href="#uv-pip-compile--exclude-newer-package"><code>--exclude-newer-package</code></a> <i>exclude-newer-package</i></dt><dd><p>Limit candidate packages for a specific package to those that were uploaded prior to the given date.</p>
<p>Accepts package-date pairs in the format <code>PACKAGE=DATE</code>, where <code>DATE</code> is an RFC 3339 timestamp (e.g., <code>2006-12-02T02:07:43Z</code>) or local date (e.g., <code>2006-12-02</code>) in your system's configured time zone.</p>
<p>Can be provided multiple times for different packages.</p>
</dd><dt id="uv-pip-compile--extra"><a href="#uv-pip-compile--extra"><code>--extra</code></a> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
</dd><dt id="uv-pip-compile--excludes"><a href="#uv-pip-compile--excludes"><code>--excludes</code></a>, <code>--exclude</code> <i>excludes</i></dt><dd><p>Exclude packages from resolution using the given requirements files.</p>
<p>Excludes files are <code>requirements.txt</code>-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.</p>
<p>May also be set with the <code>UV_EXCLUDE</code> environment variable.</p></dd><dt id="uv-pip-compile--extra"><a href="#uv-pip-compile--extra"><code>--extra</code></a> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
<p>Only applies to <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code> sources.</p>
</dd><dt id="uv-pip-compile--extra-index-url"><a href="#uv-pip-compile--extra-index-url"><code>--extra-index-url</code></a> <i>extra-index-url</i></dt><dd><p>(Deprecated: use <code>--index</code> instead) Extra URLs of package indexes to use, in addition to <code>--index-url</code>.</p>
<p>Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.</p>
@ -4647,7 +4651,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDIT
<p>May also be set with the <code>UV_EXCLUDE_NEWER</code> environment variable.</p></dd><dt id="uv-pip-install--exclude-newer-package"><a href="#uv-pip-install--exclude-newer-package"><code>--exclude-newer-package</code></a> <i>exclude-newer-package</i></dt><dd><p>Limit candidate packages for specific packages to those that were uploaded prior to the given date.</p>
<p>Accepts package-date pairs in the format <code>PACKAGE=DATE</code>, where <code>DATE</code> is an RFC 3339 timestamp (e.g., <code>2006-12-02T02:07:43Z</code>) or local date (e.g., <code>2006-12-02</code>) in your system's configured time zone.</p>
<p>Can be provided multiple times for different packages.</p>
</dd><dt id="uv-pip-install--extra"><a href="#uv-pip-install--extra"><code>--extra</code></a> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
</dd><dt id="uv-pip-install--excludes"><a href="#uv-pip-install--excludes"><code>--excludes</code></a>, <code>--exclude</code> <i>excludes</i></dt><dd><p>Exclude packages from resolution using the given requirements files.</p>
<p>Excludes files are <code>requirements.txt</code>-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.</p>
<p>May also be set with the <code>UV_EXCLUDE</code> environment variable.</p></dd><dt id="uv-pip-install--extra"><a href="#uv-pip-install--extra"><code>--extra</code></a> <i>extra</i></dt><dd><p>Include optional dependencies from the specified extra name; may be provided more than once.</p>
<p>Only applies to <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code> sources.</p>
</dd><dt id="uv-pip-install--extra-index-url"><a href="#uv-pip-install--extra-index-url"><code>--extra-index-url</code></a> <i>extra-index-url</i></dt><dd><p>(Deprecated: use <code>--index</code> instead) Extra URLs of package indexes to use, in addition to <code>--index-url</code>.</p>
<p>Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.</p>

12
docs/reference/environment.md
View file

@ -15,7 +15,7 @@ Python can lead to unexpected behavior.
### `UV_BUILD_CONSTRAINT`
<small class="added-in">added in `0.2.34`</small>
Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file
Equivalent to the `--build-constraints` command-line argument. If set, uv will use this file
as constraints for any source distribution builds. Uses space-separated list of files.
### `UV_CACHE_DIR`
@ -62,7 +62,7 @@ local `uv.toml` file to use as the configuration file.
### `UV_CONSTRAINT`
<small class="added-in">added in `0.1.36`</small>
Equivalent to the `--constraint` command-line argument. If set, uv will use this
Equivalent to the `--constraints` command-line argument. If set, uv will use this
file as the constraints file. Uses space-separated list of files.
### `UV_CREDENTIALS_DIR`
@ -103,6 +103,12 @@ compatibility.
`.env` files from which to load environment variables when executing `uv run` commands.
### `UV_EXCLUDE`
<small class="added-in">added in `0.9.8`</small>
Equivalent to the `--excludes` command-line argument. If set, uv will use this
as the excludes file. Uses space-separated list of files.
### `UV_EXCLUDE_NEWER`
<small class="added-in">added in `0.2.12`</small>
@ -405,7 +411,7 @@ Equivalent to the `--offline` command-line argument. If set, uv will disable net
### `UV_OVERRIDE`
<small class="added-in">added in `0.2.22`</small>
Equivalent to the `--override` command-line argument. If set, uv will use this file
Equivalent to the `--overrides` command-line argument. If set, uv will use this file
as the overrides file. Uses space-separated list of files.
### `UV_PRERELEASE`

31
docs/reference/settings.md
View file

@ -202,6 +202,37 @@ environments = ["sys_platform == 'darwin'"]
---
### [`exclude-dependencies`](#exclude-dependencies) {: #exclude-dependencies }
Dependencies to exclude when resolving the project's dependencies.
Excludes are used to prevent a package from being selected during resolution,
regardless of whether it's requested by any other package. When a package is excluded,
it will be omitted from the dependency list entirely.
Including a package as an exclusion will prevent it from being installed, even if
it's requested by transitive dependencies. This can be useful for removing optional
dependencies or working around packages with broken dependencies.
!!! note
In `uv lock`, `uv sync`, and `uv run`, uv will only read `exclude-dependencies` from
the `pyproject.toml` at the workspace root, and will ignore any declarations in other
workspace members or `uv.toml` files.
**Default value**: `[]`
**Type**: `list[str]`
**Example usage**:
```toml title="pyproject.toml"
[tool.uv]
# Exclude Werkzeug from being installed, even if transitive dependencies request it.
exclude-dependencies = ["werkzeug"]
```
---
### [`index`](#index) {: #index }
The indexes to use when resolving dependencies.