mirror of https://github.com/astral-sh/uv synced 2026-06-21 13:47:25 +00:00

Files

T

Tomasz Kramkowski ea707737bb Allow configuring preview features in uv.toml and pyproject.toml (#18437 )

## Summary

This is a continuation of the excellent work by @j-helland in #16452 and
#17202 and closes #15767.

This PR adds `preview-features` to `uv.toml` and `pyproject.toml`.

This field can be set to a boolean or to a list of features.

It is intended to supersede the `preview` setting itself, and conflicts
with it.

There's a little bit of complexity required to ensure that setting
either `preview` or `preview-features` is combined at the right point,
but it's also necessary to leave them split to accurately warn when a
`uv.toml` masks a `pyproject.toml` in the same directory.

Additionally there's complexity involved in making things work with
`deny_unknown_fields` and `flatten` (they're incompatible so require
manual flattening) and also this improves error messages somewhat.

Also (supersedes) closes #16452 and (supersedes) closes #17202.

## Test Plan

Tests taken from the original PR with some alterations and a bunch of
additional tests.

---------

Co-authored-by: j-helland <jonathan.w.helland@gmail.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>

2026-06-14 11:06:53 +00:00

3.8 KiB

Raw Blame History

Preview features

uv includes opt-in preview features to provide an opportunity for community feedback and increase confidence that changes are a net-benefit before enabling them for everyone.

Enabling preview features

To enable all preview features, use the --preview flag:

$ uv run --preview ...

Or, set the UV_PREVIEW environment variable:

$ UV_PREVIEW=1 uv run ...

To enable specific preview features, use the --preview-features flag:

$ uv run --preview-features foo ...

The --preview-features flag can be repeated to enable multiple features:

$ uv run --preview-features foo --preview-features bar ...

Or, features can be provided in a comma separated list:

$ uv run --preview-features foo,bar ...

The UV_PREVIEW_FEATURES environment variable can be used similarly, e.g.:

$ UV_PREVIEW_FEATURES=foo,bar uv run ...

Preview features can also be enabled in uv.toml, or under [tool.uv] in pyproject.toml and PEP 723 metadata:

preview-features = ["foo", "bar"]

Set preview-features = true to enable all preview features.

Some preview features take effect before configuration files are loaded and cannot be enabled from configuration.

For backwards compatibility, enabling preview features that do not exist will warn, but not error, regardless of the source.

Using preview features

Often, preview features can be used without changing any preview settings if the behavior change is gated by some sort of user interaction, For example, while pylock.toml support is in preview, you can use uv pip install with a pylock.toml file without additional configuration because specifying the pylock.toml file indicates you want to use the feature. However, a warning will be displayed that the feature is in preview. The preview feature can be enabled to silence the warning.

Available preview features

The following preview features are available:

add-bounds: Allows configuring the default bounds for uv add invocations.
json-output: Allows --output-format json for various uv commands.
package-conflicts: Allows defining workspace conflicts at the package level.
pylock: Allows installing from pylock.toml files.
python-install-default: Allows installing python and python3 executables.
format: Allows using uv format.
index-exclude-newer: Allows setting exclude-newer on configured package indexes.
azure-endpoint: Allows signing requests to Azure Blob Storage endpoints with Azure credentials.
native-auth: Enables storage of credentials in a system-native location.
auth-helper: Allows using uv auth helper as a credential helper for external tools.
workspace-metadata: Allows using uv workspace metadata.
workspace-dir: Allows using uv workspace dir.
workspace-list: Allows using uv workspace list.
target-workspace-discovery: Uses the directory containing a local uv run target, rather than the current working directory, as the starting point for project and workspace discovery. This feature takes effect before configuration is loaded.
project-directory-must-exist: Rejects an invalid --project path instead of warning and continuing. Except for uv init, the path must already exist as a directory or point to a pyproject.toml file. This feature takes effect before configuration is loaded.
malware-check: Allows uv sync and other commands to check for malware using OSV before installing packages.

Disabling preview features

The --no-preview option can be used to disable preview features.

3.8 KiB Raw Blame History