Preview Features

Relevant source files

• crates/uv-cli/Cargo.toml
• crates/uv-cli/build.rs
• crates/uv-cli/src/lib.rs
• crates/uv-configuration/src/target_triple.rs
• crates/uv-preview/src/lib.rs
• crates/uv-settings/Cargo.toml
• crates/uv-settings/src/combine.rs
• crates/uv-settings/src/lib.rs
• crates/uv-settings/src/settings.rs
• crates/uv-static/src/env_vars.rs
• crates/uv/src/commands/mod.rs
• crates/uv/src/lib.rs
• crates/uv/src/settings.rs
• crates/uv/tests/it/help.rs
• crates/uv/tests/sync/show_settings.rs
• docs/concepts/preview.md
• uv.schema.json

The preview feature system in uv allows experimental or potentially breaking features to be introduced in a controlled and opt-in manner. These features are disabled by default and can be enabled via CLI flags, environment variables, or configuration files (uv.toml / pyproject.toml). This design ensures that users experience a stable default state while allowing developers and early adopters to test and provide feedback on new functionalities docs/concepts/preview.md3-6

---

Feature Gating Mechanism

Preview features are implemented as bitflags, enabling efficient runtime checks for whether a feature is enabled.

Core Data Structures and Implementation

• The preview features are enumerated in the PreviewFeature enum which uses the enumflags2 crate to represent each feature as a flag bit. This enum is defined in the uv-preview crate crates/uv-preview/src/lib.rs9-10

• The Preview struct wraps a set of these bitflags representing the enabled features crates/uv-preview/src/lib.rs131-133

• The global preview state is held in a OnceLock that stores a PreviewMode, which can be one of two variants crates/uv-preview/src/lib.rs21-29:

  1. Normal Mode: Uses a Mutex<PreviewState> wrapping the enabled features. This is the standard mode during normal CLI operation crates/uv-preview/src/lib.rs23
  2. Test Mode: Under the testing feature flag, exposes an override mechanism with a RwLock<Option<Preview>> allowing temporary patching of preview feature flags during tests crates/uv-preview/src/lib.rs26

This global state pattern ensures that preview features can be queried efficiently and remain locked for the runtime of the application once initialized.

Preview Feature Data Model

Sources: crates/uv-preview/src/lib.rs9-54

---

Global Preview State Initialization and Resolution

At startup, uv resolves preview features from multiple sources in order of precedence docs/concepts/preview.md8-51:

1. Command-line Flags:

   • --preview: Enables all preview features docs/concepts/preview.md8-9
   • --preview-features <feature-list>: Enables specific preview features by name (comma-delimited) docs/concepts/preview.md20-21
   • --no-preview: Disables preview features, overriding others docs/concepts/preview.md101

2. Environment Variables:

   • UV_PREVIEW=1: Enables all preview features docs/concepts/preview.md14-15
   • UV_PREVIEW_FEATURES=foo,bar: Enables specific features docs/concepts/preview.md38-39

3. Configuration Files:

   • uv.toml or [tool.uv] in pyproject.toml can specify preview = true or preview-features = ["foo", "bar"] docs/concepts/preview.md44-51

Resolution occurs in uv::run by calling settings::resolve_preview crates/uv/src/lib.rs155 This happens before full configuration discovery for decisions that affect the discovery root, such as TargetWorkspaceDiscovery crates/uv/src/lib.rs154-155

Data Flow Diagram

Sources: crates/uv/src/lib.rs112-160 crates/uv/src/settings.rs138 crates/uv-preview/src/lib.rs51-71 docs/concepts/preview.md8-51

---

Runtime Use: Checking Enabled Preview Flags

Within the uv codebase, the presence of preview features is checked at runtime by calling uv_preview::is_enabled(PreviewFeature::...) crates/uv-preview/src/lib.rs131-133

Example Logic: Target Workspace Discovery

If TargetWorkspaceDiscovery is enabled, uv uses the directory containing a script target as the starting point for workspace discovery rather than the Current Working Directory (CWD) crates/uv/src/lib.rs186-200

Runtime Preview Checking Flow

Sources: crates/uv-preview/src/lib.rs131-133 crates/uv/src/lib.rs186-200

---

Available Preview Features

The following list describes features currently gated behind the preview system docs/concepts/preview.md67-98:

Name (CLI/TOML)	Enum Variant	Description
audit	Audit	Scans dependencies for known vulnerabilities crates/uv/src/commands/mod.rs34
format	Format	Enables uv format (powered by Ruff) crates/uv/src/commands/mod.rs37
check	Check	Enables uv check (powered by ty) crates/uv/src/commands/mod.rs35
pylock	PyLock	Support for pylock.toml lockfile format crates/uv/src/commands/mod.rs94
native-auth	NativeAuth	Enables system-native credential storage crates/uv-cli/src/lib.rs15
azure-endpoint	AzureEndpoint	Azure Blob Storage authentication support crates/uv-cli/src/lib.rs19
gcs-endpoint	GcsEndpoint	Google Cloud Storage authentication support docs/concepts/preview.md83
s3-endpoint	S3Endpoint	Amazon S3 authentication support.
auth-helper	AuthHelper	Enables uv auth helper for external tools crates/uv/src/commands/mod.rs14
malware-check	MalwareCheck	Checks for malware via OSV during sync crates/uv-settings/src/lib.rs59
workspace-metadata	WorkspaceMetadata	Enables uv workspace metadata crates/uv/src/commands/mod.rs76
workspace-list-scripts	WorkspaceListScripts	Enables uv workspace list --scripts to list PEP 723 scripts crates/uv/src/commands/workspace/list.rs75
add-bounds	AddBounds	Default bounds for uv add crates/uv-cli/src/lib.rs38
package-conflicts	PackageConflicts	Allows defining workspace conflicts at the package level docs/concepts/preview.md77
index-exclude-newer	IndexExcludeNewer	Allows setting exclude-newer on configured package indexes docs/concepts/preview.md82
cache-size	CacheSize	Enables uv cache size command crates/uv/src/commands/mod.rs22
init-project-flag	InitProjectFlag	Allows uv init --project to create a project in a specified directory.
sbom-export	SbomExport	CycloneDX SBOM export support.
extra-build-dependencies	ExtraBuildDependencies	Allows specifying extra build dependencies crates/uv-settings/src/lib.rs67
detect-module-conflicts	DetectModuleConflicts	Detects module conflicts during resolution.
python-install-default	PythonInstallDefault	Allows installing python and python3 executables docs/concepts/preview.md79-80
json-output	JsonOutput	JSON output for various commands crates/uv-cli/src/lib.rs50
direct-publish	DirectPublish	Enables publishing without OIDC.
target-workspace-discovery	TargetWorkspaceDiscovery	Discovery based on target script location crates/uv/src/lib.rs155
metadata-json	MetadataJson	Enables JSON output for metadata commands.
adjust-ulimit	AdjustUlimit	Adjusts the file descriptor limit.
special-conda-env-names	SpecialCondaEnvNames	Allows special Conda environment names.
relocatable-envs-default	RelocatableEnvsDefault	Makes environments relocatable by default.
publish-require-normalized	PublishRequireNormalized	Requires normalized package names for publishing.
project-directory-must-exist	ProjectDirectoryMustExist	Validates --project path exists crates/uv/src/lib.rs186
toml-backwards-compatibility	TomlBackwardsCompatibility	Enables backwards compatibility for TOML parsing.
venv-safe-clear	VenvSafeClear	Requires --clear to remove existing environments with uv venv.
packaged-init	PackagedInit	Makes packaged applications the default for uv init.
centralized-project-envs	CentralizedProjectEnvs	Stores project virtual environments in the uv cache docs/concepts/preview.md73-75
tool-install-locks	ToolInstallLocks	Locks tool environments during installation.
no-distutils-patch	NoDistutilsPatch	Disables patching of distutils in virtual environments.

Stabilized Features in 0.10.0

The following features, previously in preview, have been stabilized in uv version 0.10.0:

• Python Upgrade: The uv python upgrade command and uv python install --upgrade are now stable crates/uv/src/commands/mod.rs51
• Add Bounds: The ability to configure default bounds for uv add invocations is now stable crates/uv-settings/src/lib.rs68
• Extra Build Dependencies: Specifying extra build dependencies is now stable crates/uv-settings/src/lib.rs67
• Workspace Directory: The uv workspace dir command is now stable crates/uv/src/commands/mod.rs74
• Workspace List: The uv workspace list command is now stable crates/uv/src/commands/mod.rs75
• Venv Safe Clear: The behavior of uv venv requiring --clear to remove existing environments is now default.

New 0.11.x Preview Features

• Index-specific hash-algorithm: Allows specifying hashing algorithms per index.
• Workspace cross-references: Allows workspace members to reference members in other workspaces by path.

Sources: crates/uv-preview/src/lib.rs9-133 crates/uv/src/lib.rs112-200 crates/uv-cli/src/lib.rs14-43 crates/uv/src/commands/mod.rs13-76 docs/concepts/preview.md67-98

---

Testing Infrastructure

The uv-preview crate provides test::with_features to allow unit and integration tests to isolate experimental behavior crates/uv-preview/src/lib.rs174

• Serial Execution: A static MUTEX ensures tests relying on global preview state run serially crates/uv-preview/src/lib.rs146
• Thread Locality: The HELD thread-local cell tracks if the current thread holds the FeaturesGuard crates/uv-preview/src/lib.rs148-154
• Safety: Attempting to call with_features while already holding a guard or calling set() in test mode will result in a panic or error crates/uv-preview/src/lib.rs69-178

Sources: crates/uv-preview/src/lib.rs136-180