预览功能
uv 包含选择性启用的预览功能,旨在收集社区反馈,并在向所有用户开放之前,确保这些变更确实能带来净收益。
启用预览功能
要启用所有预览功能,请使用 --preview 标志:
或者,设置 UV_PREVIEW 环境变量:
要启用特定的预览功能,请使用 --preview-features 标志:
--preview-features 标志可以重复使用以启用多个功能:
或者,功能可以以逗号分隔列表的形式提供:
UV_PREVIEW_FEATURES 环境变量也可以类似地使用,例如:
预览功能也可以在 uv.toml 中启用,或者在 pyproject.toml 和 PEP 723 元数据中的 [tool.uv] 下启用:
设置 preview-features = true 可以启用所有预览功能。
部分预览功能在配置文件加载之前就已生效,因此无法通过配置文件启用。
为了向后兼容性,启用不存在的预览功能会发出警告,但不会报错,无论来自何种配置来源。
使用预览功能
通常,如果行为变更是由某种用户交互触发的,则无需更改任何预览设置即可使用预览功能。例如,当 pylock.toml 支持处于预览阶段时,你可以直接使用 uv pip install 配合 pylock.toml 文件,而无需额外配置,因为指定 pylock.toml 文件本身就表明你希望使用该功能。不过,系统会显示一条警告,提示该功能处于预览阶段。启用该预览功能可以消除此警告。
可用的预览功能
以下预览功能目前可用:
add-bounds:允许配置uv add的默认边界。json-output:允许在各种 uv 命令中使用--output-format json。package-conflicts:允许在包级别定义工作区冲突。pylock:允许从pylock.toml文件安装。python-install-default:允许安装python和python3可执行文件。format:允许使用uv format。index-exclude-newer:允许在已配置的包索引上设置exclude-newer。azure-endpoint:允许使用 Azure 凭据对 Azure Blob Storage 端点的请求进行签名。native-auth:允许将凭据存储在系统原生位置。auth-helper:允许将uv auth helper用作外部工具的凭据辅助工具。workspace-metadata:允许使用uv workspace metadata。workspace-dir:允许使用uv workspace dir。workspace-list:允许使用uv workspace list。target-workspace-discovery:使用包含本地uv run目标的目录(而非当前工作目录)作为项目和工作区发现的起点。此功能在配置加载之前就已生效。project-directory-must-exist:拒绝无效的--project路径,而不是发出警告并继续执行。除uv init外,该路径必须已作为目录存在或指向一个pyproject.toml文件。此功能在配置加载之前就已生效。malware-check:允许uv sync及其他命令在安装包之前通过 OSV 检查恶意软件。
禁用预览功能
--no-preview 选项可用于禁用预览功能。