uv workspace

查看 uv 工作空间

Usage

uv workspace [OPTIONS] <COMMAND>

Commands

uv workspace metadata: 查看当前工作空间的元数据
uv workspace dir: 显示工作空间成员的路径
uv workspace list: 列出工作空间的成员

uv workspace metadata

查看当前工作空间的元数据。

此命令的输出尚未稳定。

Usage

uv workspace metadata [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如 localhost）、主机-端口对（例如 localhost:8080）或 URL（例如 https://localhost）。

警告：此列表中的主机将不会根据系统证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它会绕过 SSL 验证，可能使您面临中间人攻击。

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

缓存目录的路径。

在 macOS 和 Linux 上默认为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，在 Windows 上默认为 %LOCALAPPDATA%\uv\cache。

要查看缓存目录的位置，请运行 uv cache dir。

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测颜色支持。

可能的值：

auto: 仅在输出到支持颜色的终端或 TTY 时启用彩色输出
always: 无论检测到的环境如何，都启用彩色输出
never: 禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

传递给 PEP 517 构建后端的设置，以 KEY=VALUE 对的形式指定

--config-settings-package, --config-settings-package config-settings-package

传递给特定包 PEP 517 构建后端的设置，以 PACKAGE:KEY=VALUE 对的形式指定

--default-index default-index

默认包索引的 URL（默认为 https://pypi.org/simple）。

接受符合 PEP 503（简单仓库 API）的仓库，或以相同格式组织的本地目录。

此标志指定的索引优先级低于通过 --index 标志指定的所有其他索引。

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

在运行命令之前切换到给定目录。

相对路径以给定目录为基准进行解析。

参见 --project 仅更改项目根目录。

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

执行试运行，不写入锁文件。

在试运行模式下，uv 将解析项目的依赖关系并报告结果更改，但不会将锁文件写入磁盘。

--exclude-newer exclude-newer

将候选包限制为在给定日期之前上传的包。

日期与每个单独分发制品（即每个文件上传到包索引的时间）的上传时间进行比较，而不是与包版本的发布日期进行比较。

接受 RFC 3339 时间戳（例如 2006-12-02T02:07:43Z）、基于系统配置时区解析的相同格式本地日期（例如 2006-12-02）、"友好"持续时间（例如 24 hours、1 week、30 days）或 ISO 8601 持续时间（例如 PT24H、P7D、P30D）。

持续时间不遵循本地时区的语义，始终解析为固定秒数，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月份和年份等日历单位。

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

将特定包的候选包限制为在给定日期之前上传的包。

接受 PACKAGE=DATE 格式的包-日期对，其中 DATE 是 RFC 3339 时间戳（例如 2006-12-02T02:07:43Z）、基于系统配置时区解析的相同格式本地日期（例如 2006-12-02）、"友好"持续时间（例如 24 hours、1 week、30 days）或 ISO 8601 持续时间（例如 PT24H、P7D、P30D）。

持续时间不遵循本地时区的语义，始终解析为固定秒数，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月份和年份等日历单位。

可以为不同的包多次提供。

--extra-index-url extra-index-url

（已弃用：请改用 --index）除 --index-url 之外要使用的额外包索引 URL。

接受符合 PEP 503（简单仓库 API）的仓库，或以相同格式组织的本地目录。

通过此标志提供的所有索引优先级高于 --index-url 指定的索引（默认为 PyPI）。当提供多个 --extra-index-url 标志时，较早的值优先。

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

除了在注册表索引中找到的之外，还要搜索候选分发的位置。

如果是路径，目标必须是一个目录，顶层包含 wheel 文件（.whl）或源分发（例如 .tar.gz 或 .zip）形式的包。

如果是 URL，页面必须包含一个符合上述格式的包文件链接的扁平列表。

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

在跨 Python 版本和平台选择给定包的多个版本时使用的策略。

默认情况下，uv 会优化为每个受支持的 Python 版本（requires-python）选择每个包的最新版本，同时尽量减少跨平台选择的版本数量。

在 fewest 策略下，uv 会尽量减少每个包选择的版本数量，优先选择与更广泛受支持的 Python 版本或平台兼容的旧版本。

May also be set with the UV_FORK_STRATEGY environment variable.

可能的值：

fewest: 优化为选择每个包的最少版本数量。如果旧版本与更广泛的受支持 Python 版本或平台兼容，则可能优先选择旧版本
requires-python: 优化为每个受支持的 Python 版本选择每个包的最新支持版本

--frozen

断言 uv.lock 存在，但不检查它是否是最新的 [env: UV_FROZEN=]

--help, -h

显示此命令的简明帮助

--index index

解析依赖关系时使用的 URL，作为默认索引的补充。

接受符合 PEP 503（简单仓库 API）的仓库，或以相同格式组织的本地目录。

通过此标志提供的所有索引优先级高于 --default-index 指定的索引（默认为 PyPI）。当提供多个 --index 标志时，较早的值优先。

不支持将索引名称作为值。在 Unix 上，相对路径必须使用 ./ 或 ../ 与索引名称区分，在 Windows 上使用 .\\、..\\、./ 或 ../。

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

针对多个索引 URL 进行解析时使用的策略。

默认情况下，uv 会在第一个找到给定包的索引处停止，并将解析限制为该第一个索引上存在的包（first-index）。这可以防止"依赖混淆"攻击，即攻击者可以在备用索引上以相同名称上传恶意包。

May also be set with the UV_INDEX_STRATEGY environment variable.

可能的值：

first-index: 仅使用第一个为给定包名返回匹配结果的索引
unsafe-first-match: 在所有索引中搜索每个包名，在移动到下一个索引之前穷尽第一个索引的版本
unsafe-best-match: 在所有索引中搜索每个包名，优先选择找到的"最佳"版本。如果一个包版本存在于多个索引中，则只查看第一个索引的条目

--index-url, -i index-url

（已弃用：请改用 --default-index）Python 包索引的 URL（默认为 https://pypi.org/simple）。

接受符合 PEP 503（简单仓库 API）的仓库，或以相同格式组织的本地目录。

此标志指定的索引优先级低于通过 --extra-index-url 标志指定的所有其他索引。

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

尝试使用 keyring 对索引 URL 进行身份验证。

目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。

默认为 disabled。

May also be set with the UV_KEYRING_PROVIDER environment variable.

可能的值：

disabled: 不使用 keyring 进行凭据查找
subprocess: 使用 keyring 命令进行凭据查找

--link-mode link-mode

从全局缓存安装包时使用的方法。

此选项仅在构建源代码分发时使用。

在 macOS 和 Linux 上默认为 clone（也称为写时复制），在 Windows 上默认为 hardlink。

警告：不鼓励使用 symlink 链接模式，因为它会在缓存和目标环境之间创建紧密耦合。例如，清除缓存（uv cache clean）将通过删除底层源文件来破坏所有已安装的包。请谨慎使用 symlink。

May also be set with the UV_LINK_MODE environment variable.

可能的值：

clone: 将包从源克隆（即写时复制）到目标
copy: 将包从源复制到目标
hardlink: 将包从源硬链接到目标
symlink: 将包从源符号链接到目标

--locked

检查锁文件是否是最新的 [env: UV_LOCKED=]

断言 uv.lock 在解析后保持不变。如果锁文件缺失或需要更新，uv 将退出并报错。

--managed-python

要求使用 uv 管理的 Python 版本 [env: UV_MANAGED_PYTHON=]

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果未安装 uv 管理的 Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

--no-binary

不安装预构建的 wheel。

给定的包将从源代码构建并安装。解析器仍将使用预构建的 wheel 来提取包元数据（如果可用）。

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

不为特定包安装预构建的 wheel [env: UV_NO_BINARY_PACKAGE=]

--no-build

不构建源代码分发。

启用后，解析将不会运行任意 Python 代码。已构建的源代码分发的缓存 wheel 将被重用，但需要构建分发的操作将退出并报错。

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

在构建源代码分发时禁用隔离。

假定 PEP 518 指定的构建依赖项已安装。

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

在构建特定包的源代码分发时禁用隔离。

假定该包由 PEP 518 指定的构建依赖项已安装。

--no-build-package no-build-package

不为特定包构建源代码分发 [env: UV_NO_BUILD_PACKAGE=]

--no-cache, --no-cache-dir, -n

避免读取或写入缓存，而是在操作期间使用临时目录

May also be set with the UV_NO_CACHE environment variable.

--no-config

避免发现配置文件（pyproject.toml、uv.toml）。

通常，配置文件会在当前目录、父目录或用户配置目录中被发现。

May also be set with the UV_NO_CONFIG environment variable.

--no-index

忽略注册表索引（例如 PyPI），转而依赖直接 URL 依赖项和通过 --find-links 提供的依赖项

--no-managed-python

禁用 uv 管理的 Python 版本 [env: UV_NO_MANAGED_PYTHON=]

相反，uv 将在系统上搜索合适的 Python 版本。

--no-progress

隐藏所有进度输出 [env: UV_NO_PROGRESS=]

例如，旋转指示器或进度条。

--no-python-downloads

禁用自动下载 Python。

--no-sources

在解析依赖关系时忽略 tool.uv.sources 表。用于根据符合标准、可发布的包元数据进行锁定，而不是使用任何工作空间、Git、URL 或本地路径源

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

不对指定的包使用 tool.uv.sources 表中的源 [env: UV_NO_SOURCES_PACKAGE=]

--offline

禁用网络访问 [env: UV_OFFLINE=]

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

--prerelease prerelease

考虑预发布版本时使用的策略。

默认情况下，uv 将接受仅发布预发布版本的包，以及在其声明的版本说明符中包含显式预发布标记的第一方需求（if-necessary-or-explicit）。

May also be set with the UV_PRERELEASE environment variable.

可能的值：

disallow: 不允许所有预发布版本
allow: 允许所有预发布版本
if-necessary: 如果包的所有版本都是预发布版本，则允许预发布版本
explicit: 允许在其版本需求中包含显式预发布标记的第一方包的预发布版本
if-necessary-or-explicit: 如果包的所有版本都是预发布版本，或包在其版本需求中包含显式预发布标记，则允许预发布版本

--project project

在给定目录中发现项目。

所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也是如此。

其他命令行参数（如相对路径）将相对于当前工作目录进行解析。

参见 --directory 完全更改工作目录。

此设置在 uv pip 接口中使用时无效。

May also be set with the UV_PROJECT environment variable.

--python, -p python

解析期间使用的 Python 解释器。

当没有 wheel 时，构建源代码分发需要 Python 解释器来确定包元数据。

如果未设置 requires-python，该解释器也用作最低 Python 版本的回退值。

有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。

May also be set with the UV_PYTHON environment variable.

--quiet, -q

使用静默输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会向 stdout 写入任何输出。

--refresh

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--resolution resolution

在给定包需求的不同兼容版本之间进行选择时使用的策略。

默认情况下，uv 将使用每个包的最新兼容版本（highest）。

May also be set with the UV_RESOLUTION environment variable.

可能的值：

highest: 解析每个包的最高兼容版本
lowest: 解析每个包的最低兼容版本
lowest-direct: 解析所有直接依赖项的最低兼容版本，以及任何传递依赖项的最高兼容版本

--script script

查看指定 PEP 723 Python 脚本的元数据，而不是当前工作空间。

如果提供，uv 将根据脚本的内联元数据表解析依赖关系，遵循 PEP 723。

--sync

同步环境以在输出中包含模块所有权元数据。

这将添加一个从可导入模块名称到提供它们的包节点引用的映射。为此，venv 将以非精确模式同步。

--system-certs

是否从平台的原生证书存储加载 TLS 证书 [env: UV_SYSTEM_CERTS=]

默认情况下，uv 使用捆绑的 Mozilla 根证书，这提高了可移植性和性能（尤其在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的原生证书存储，特别是如果您依赖系统证书存储中包含的企业信任根（例如，用于强制代理）。

--upgrade, -U

允许包升级，忽略任何现有输出文件中的固定版本。隐含 --refresh

--upgrade-group upgrade-group

允许依赖组中所有包的升级，忽略任何现有输出文件中的固定版本

--upgrade-package, -P upgrade-package

允许特定包的升级，忽略任何现有输出文件中的固定版本。隐含 --refresh-package

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv workspace dir

显示工作空间成员的路径。

默认情况下，显示工作空间根目录的路径。可以使用 --package 选项来显示工作空间成员的路径。

如果在工作空间之外使用，即找不到 pyproject.toml，uv 将退出并报错。

Usage

uv workspace dir [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如 localhost）、主机-端口对（例如 localhost:8080）或 URL（例如 https://localhost）。

警告：此列表中的主机将不会根据系统证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它会绕过 SSL 验证，可能使您面临中间人攻击。

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

缓存目录的路径。

在 macOS 和 Linux 上默认为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，在 Windows 上默认为 %LOCALAPPDATA%\uv\cache。

要查看缓存目录的位置，请运行 uv cache dir。

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测颜色支持。

可能的值：

auto: 仅在输出到支持颜色的终端或 TTY 时启用彩色输出
always: 无论检测到的环境如何，都启用彩色输出
never: 禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

在运行命令之前切换到给定目录。

相对路径以给定目录为基准进行解析。

参见 --project 仅更改项目根目录。

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

显示此命令的简明帮助

--managed-python

要求使用 uv 管理的 Python 版本 [env: UV_MANAGED_PYTHON=]

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果未安装 uv 管理的 Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

--no-cache, --no-cache-dir, -n

避免读取或写入缓存，而是在操作期间使用临时目录

May also be set with the UV_NO_CACHE environment variable.

--no-config

避免发现配置文件（pyproject.toml、uv.toml）。

通常，配置文件会在当前目录、父目录或用户配置目录中被发现。

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

禁用 uv 管理的 Python 版本 [env: UV_NO_MANAGED_PYTHON=]

相反，uv 将在系统上搜索合适的 Python 版本。

--no-progress

隐藏所有进度输出 [env: UV_NO_PROGRESS=]

例如，旋转指示器或进度条。

--no-python-downloads

禁用自动下载 Python。

--offline

禁用网络访问 [env: UV_OFFLINE=]

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

--package package

显示工作空间中特定包的路径

--project project

在给定目录中发现项目。

所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也是如此。

其他命令行参数（如相对路径）将相对于当前工作目录进行解析。

参见 --directory 完全更改工作目录。

此设置在 uv pip 接口中使用时无效。

May also be set with the UV_PROJECT environment variable.

--quiet, -q

使用静默输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会向 stdout 写入任何输出。

--system-certs

是否从平台的原生证书存储加载 TLS 证书 [env: UV_SYSTEM_CERTS=]

默认情况下，uv 使用捆绑的 Mozilla 根证书，这提高了可移植性和性能（尤其在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的原生证书存储，特别是如果您依赖系统证书存储中包含的企业信任根（例如，用于强制代理）。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv workspace list

列出工作空间的成员。

显示以换行符分隔的工作空间成员名称。

Usage

uv workspace list [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如 localhost）、主机-端口对（例如 localhost:8080）或 URL（例如 https://localhost）。

警告：此列表中的主机将不会根据系统证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它会绕过 SSL 验证，可能使您面临中间人攻击。

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

缓存目录的路径。

在 macOS 和 Linux 上默认为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，在 Windows 上默认为 %LOCALAPPDATA%\uv\cache。

要查看缓存目录的位置，请运行 uv cache dir。

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测颜色支持。

可能的值：

auto: 仅在输出到支持颜色的终端或 TTY 时启用彩色输出
always: 无论检测到的环境如何，都启用彩色输出
never: 禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

在运行命令之前切换到给定目录。

相对路径以给定目录为基准进行解析。

参见 --project 仅更改项目根目录。

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

显示此命令的简明帮助

--managed-python

要求使用 uv 管理的 Python 版本 [env: UV_MANAGED_PYTHON=]

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果未安装 uv 管理的 Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

--no-cache, --no-cache-dir, -n

避免读取或写入缓存，而是在操作期间使用临时目录

May also be set with the UV_NO_CACHE environment variable.

--no-config

避免发现配置文件（pyproject.toml、uv.toml）。

通常，配置文件会在当前目录、父目录或用户配置目录中被发现。

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

禁用 uv 管理的 Python 版本 [env: UV_NO_MANAGED_PYTHON=]

相反，uv 将在系统上搜索合适的 Python 版本。

--no-progress

隐藏所有进度输出 [env: UV_NO_PROGRESS=]

例如，旋转指示器或进度条。

--no-python-downloads

禁用自动下载 Python。

--offline

禁用网络访问 [env: UV_OFFLINE=]

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

--paths

显示路径而不是名称

--project project

在给定目录中发现项目。

所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也是如此。

其他命令行参数（如相对路径）将相对于当前工作目录进行解析。

参见 --directory 完全更改工作目录。

此设置在 uv pip 接口中使用时无效。

May also be set with the UV_PROJECT environment variable.

--quiet, -q

使用静默输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会向 stdout 写入任何输出。

--system-certs

是否从平台的原生证书存储加载 TLS 证书 [env: UV_SYSTEM_CERTS=]

默认情况下，uv 使用捆绑的 Mozilla 根证书，这提高了可移植性和性能（尤其在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的原生证书存储，特别是如果您依赖系统证书存储中包含的企业信任根（例如，用于强制代理）。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)