3.17 预览特性

原文链接: https://docs.astral.sh/uv/concepts/preview/

3.17 预览特性

uv 包含需要显式启用的预览特性，以便收集社区反馈，并在面向所有人启用之前提高对“这些改动确有益处”的信心。

启用预览特性

要启用所有预览特性，请使用 --preview 标志：

1

$ uv run --preview ...

或者设置 UV_PREVIEW 环境变量：

1

$ UV_PREVIEW=1 uv run ...

要启用特定的预览特性，请使用 --preview-features 标志：

1

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

--preview-features 标志可以重复使用以启用多个特性：

1

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

也可以用逗号分隔的列表提供多个特性：

1

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

UV_PREVIEW_FEATURES 环境变量的用法类似，例如：

1

$ UV_PREVIEW_FEATURES=foo,bar uv run ...

预览特性也可以在 uv.toml、pyproject.toml 的 [tool.uv] 下或 PEP 723 元数据中启用：

1

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

设置 preview-features = true 可启用所有预览特性。

某些预览特性在配置文件加载之前就会生效，无法通过配置启用。

为了向后兼容，启用不存在的预览特性只会给出警告而不会报错，无论来自哪种来源。

使用预览特性

通常，如果行为变化由某种用户交互决定，那么无需更改任何预览设置即可使用预览特性。例如，在 pylock.toml 支持处于预览阶段时，你可以直接用 uv pip install 加 pylock.toml 文件而无需额外配置，因为指定 pylock.toml 文件本身就表示你想使用该特性。不过会显示一条提示该特性处于预览阶段的警告。启用该预览特性即可消除警告。

可用的预览特性

以下预览特性可用：

• add-bounds：允许为 uv add 调用配置默认的版本范围。
• adjust-ulimit：在 Unix 上，启动时把进程的软性打开文件数限制提升到硬性限制。
• artifact-hash-filtering：把生成的 requirement 哈希限制为二进制与构建策略所允许的产物。
• audit-command：允许使用 uv audit 和 uv tool audit。
• auth-helper：允许把 uv auth helper 用作外部工具的凭据助手。
• azure-endpoint：允许使用 Azure 凭据为发往 Azure Blob Storage 端点的请求签名。
• batch-export：允许使用 uv export --batch。
• build-dependency-check：在 uv build 进行非隔离构建之前检查构建依赖。
• build-lazy-imports：在 CPython 3.15 及更高版本的构建后端调用中启用惰性导入。这可能影响第三方构建后端的导入期副作用。
• cache-physical-space：报告缓存清理实际回收的物理磁盘空间，并计入硬链接和写时复制克隆。
• cache-size：允许使用 uv cache size。
• centralized-project-envs：把项目虚拟环境存储在 uv 缓存中。
• check-command：允许使用 uv check。
• content-addressed-cache：在缓存中启用内容寻址的 wheel 归档。
• detect-module-conflicts：当多个包会向同一环境安装冲突的 Python 模块时发出警告。
• extra-build-dependencies：允许为包构建指定额外依赖。
• format-command：允许使用 uv format。
• gcs-endpoint：允许为发往已配置 Google Cloud Storage 端点的请求签名。
• index-by-name：允许用 --index 和 --default-index 按名称选择已配置的包索引。
• index-exclude-newer：允许在已配置的包索引上设置 exclude-newer。
• index-hash-algorithm：允许为已配置的包索引要求哈希算法。
• init-project-flag：拒绝 uv init 中已废弃的 --project 选项。
• json-output：允许各种 uv 命令使用 --output-format json。
• lock-without-metadata：从 uv.lock 中省略 package.metadata，远程 URL 依赖除外。
• lockfile-format-check：在使用 --locked 或 --check 时拒绝非规范格式的锁文件。
• malware-check：允许 uv sync 等命令在安装包之前通过 OSV 检查恶意软件。
• metadata-json：在构建的 wheel 中包含 JSON 元数据文件。
• minimum-libc-version：允许为通用解析设置最低 libc 版本。
• missing-exclude-newer-package-lock：当 exclude-newer-package 条目未包含在项目已解析的依赖中时，把它们从锁文件中排除。
• native-auth：允许把凭据存储在系统原生位置。
• no-distutils-patch：在 Python 3.10 及更高版本的虚拟环境中，不再安装 _virtualenv.py / _virtualenv.pth 的 distutils 配置猴子补丁。
• package-conflicts：允许在包级别定义工作区冲突。
• packaged-init：让 uv init 默认创建带 src/ 布局、构建系统和脚本入口点的可打包应用。
• project-directory-must-exist：拒绝无效的 --project 路径，而不是警告后继续。除 uv init 之外，该路径必须已作为目录存在，或指向一个 pyproject.toml 文件。该特性在配置加载之前就会生效。
• publish-require-normalized：发布时要求文件名已规范化，跳过名称未规范化的文件。
• pylock：允许从 pylock.toml 文件安装。
• python-install-default：允许安装 python 和 python3 可执行文件。
• relocatable-envs-default：默认创建可重定位的虚拟环境。
• resolution-inputs：记录运行时的配置查询，并从锁文件中省略未使用的约束、覆盖、排除项、依赖元数据和针对特定包的上传截止时间。
• s3-endpoint：允许为发往已配置的 S3 兼容端点的请求签名。
• sbom-export：允许使用 uv export --format=cyclonedx1.5。
• special-conda-env-names：不再把名为 base 或 root 的 Conda 环境视为特殊环境。
• tar-codec：使用新的 tar-codec 编解码后端，而不是 astral-tokio-tar。
• target-workspace-discovery：以包含本地 uv run 目标的目录（而不是当前工作目录）作为项目与工作区发现的起点。该特性在配置加载之前就会生效。
• toml-backwards-compatibility：构建源码分发时把 pyproject.toml 重写为 TOML 1.0，并把原始文件保留为 pyproject.toml.orig，以确保与旧构建工具兼容。
• tool-install-locks：为每个已安装工具存储一份 uv.lock，并在可复现的安装、升级和审计中复用它。
• venv-safe-clear：阻止 uv venv --clear 清空不包含 pyvenv.cfg 文件的目录，除非提供了 --force。
• workspace-dir：允许使用 uv workspace dir。
• workspace-list：允许使用 uv workspace list。
• workspace-list-scripts：允许使用 uv workspace list --scripts。
• workspace-metadata：允许使用 uv workspace metadata。

禁用预览特性

--no-preview 选项可用于禁用预览特性。