Skip to content

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.
  • adjust-ulimit: On Unix, raises the process's soft open-file limit at startup, up to the hard limit.
  • audit-command: Allows using uv audit and uv tool audit.
  • auth-helper: Allows using uv auth helper as a credential helper for external tools.
  • azure-endpoint: Allows signing requests to Azure Blob Storage endpoints with Azure credentials.
  • cache-physical-space: Reports the physical disk space reclaimed by cache cleanup, accounting for hardlinks and copy-on-write clones.
  • cache-size: Allows using uv cache size.
  • centralized-project-envs: Stores project virtual environments in the uv cache.
  • check-command: Allows using uv check.
  • detect-module-conflicts: Warns when multiple packages would install conflicting Python modules into the same environment.
  • direct-publish: Allows publishing directly to a package index.
  • extra-build-dependencies: Allows specifying additional dependencies for package builds.
  • format-command: Allows using uv format.
  • gcs-endpoint: Allows signing requests to configured Google Cloud Storage endpoints.
  • index-exclude-newer: Allows setting exclude-newer on configured package indexes.
  • index-hash-algorithm: Allows requiring a hash algorithm for configured package indexes.
  • init-project-flag: Rejects the deprecated --project option in uv init.
  • json-output: Allows --output-format json for various uv commands.
  • lock-without-metadata: Omit package.metadata from uv.lock.
  • lockfile-format-check: Rejects non-canonical lockfile formatting when using --locked or --check.
  • malware-check: Allows uv sync and other commands to check for malware using OSV before installing packages.
  • metadata-json: Includes JSON metadata files in built wheels.
  • native-auth: Enables storage of credentials in a system-native location.
  • no-distutils-patch: Stops installing the _virtualenv.py / _virtualenv.pth distutils configuration monkeypatch in virtual environments for Python 3.10 and later.
  • package-conflicts: Allows defining workspace conflicts at the package level.
  • packaged-init: Makes uv init create a packaged application with a src/ layout, build system, and script entry point by default.
  • 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.
  • publish-require-normalized: Requires normalized distribution filenames when publishing, skipping files whose names are not normalized.
  • pylock: Allows installing from pylock.toml files.
  • python-install-default: Allows installing python and python3 executables.
  • relocatable-envs-default: Creates relocatable virtual environments by default.
  • s3-endpoint: Allows signing requests to configured S3-compatible endpoints.
  • sbom-export: Allows using uv export --format=cyclonedx1.5.
  • special-conda-env-names: Stops treating Conda environments named base or root as special.
  • 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.
  • toml-backwards-compatibility: Rewrites pyproject.toml as TOML 1.0 when building source distributions, preserving the original as pyproject.toml.orig to ensure compatibility with older build tools.
  • tool-install-locks: Stores a uv.lock alongside each installed tool and reuses it for reproducible installations, upgrades, and audits.
  • venv-safe-clear: Prevents uv venv --clear from clearing a directory that does not contain a pyvenv.cfg file unless --force is provided.
  • workspace-dir: Allows using uv workspace dir.
  • workspace-list: Allows using uv workspace list.
  • workspace-list-scripts: Allows using uv workspace list --scripts.
  • workspace-metadata: Allows using uv workspace metadata.

Disabling preview features

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