uv python

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

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

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--only-downloads

仅显示可用的 Python 下载。

默认情况下，会显示已安装的发行版和当前平台可用的下载。

--only-installed

仅显示已安装的 Python 版本。

默认情况下，会显示已安装的发行版和当前平台可用的下载。

--output-format output-format

选择输出格式

[默认值: text]

可选值：

text：纯文本（供人类阅读）
json：JSON（供计算机处理）

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL

--quiet, -q

使用静默输出。

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

--show-urls

显示可用 Python 下载的 URL。

默认情况下，这些显示为 <download available>。

是否从平台的原生证书存储加载 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 python install

下载并安装 Python 版本。

支持 CPython 和 PyPy。CPython 发行版从 Astral 的 python-build-standalone 项目下载。PyPy 发行版从 python.org 下载。可用的 Python 版本随每个 uv 发行版捆绑发布。要安装新的 Python 版本，您可能需要升级 uv。

Python 版本安装到 uv Python 目录中，可以通过 uv python dir 获取该目录。

默认情况下，Python 可执行文件会添加到路径中的目录中，并带有次要版本后缀，例如 python3.13。要安装 python3 和 python，请使用 --default 标志。使用 uv python dir --bin 查看目标目录。

可以请求多个 Python 版本。

请参阅 uv help python 了解支持的请求格式。

用法

uv python install [OPTIONS] [TARGETS]...

参数

TARGETS

要安装的 Python 版本。

如果未提供，请求的 Python 版本将从 UV_PYTHON 环境变量中读取，然后从 .python-versions 或 .python-version 文件中读取。如果以上都没有，uv 将检查是否已安装任何 Python 版本。如果没有，它将安装最新的稳定 Python 版本。

请参阅 uv python 了解支持的请求格式。

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--compile-bytecode, --compile

安装后将 Python 标准库编译为字节码。

默认情况下，uv 不会将 Python（.py）文件编译为字节码（__pycache__/*.pyc）；相反，编译会在首次导入模块时延迟执行。对于启动时间很重要的用例（如 CLI 应用程序和 Docker 容器），可以启用此选项，以更长的安装时间和额外的磁盘空间换取更快的启动时间。

启用后，uv 将处理 Python 版本的 stdlib 目录。它将忽略任何编译错误。

也可以通过 UV_COMPILE_BYTECODE 环境变量设置。

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--default

用作默认 Python 版本。

默认情况下，仅安装 python{major}.{minor} 可执行文件，例如 python3.10。当使用 --default 标志时，还会安装 python{major}（例如 python3）和 python 可执行文件。

替代的 Python 变体仍会包含其标签。例如，使用 --default 安装 3.13+freethreaded 将包含 python3t 和 pythont，而不是 python3 和 python。

如果请求了多个 Python 版本，uv 将退出并报错。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--force, -f

在安装过程中替换现有的 Python 可执行文件。

默认情况下，uv 会拒绝替换非其管理的可执行文件。

隐含 --reinstall。

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

存储 Python 安装的目录。

如果提供，后续操作需要设置 UV_PYTHON_INSTALL_DIR 以便 uv 发现 Python 安装。

请参阅 uv python dir 查看当前的 Python 安装目录。默认为 ~/.local/share/uv/python。

也可以通过 UV_PYTHON_INSTALL_DIR 环境变量设置。

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

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

--mirror mirror

设置用作下载 Python 安装源的 URL。

提供的 URL 将替换 https://github.com/astral-sh/python-build-standalone/releases/download，例如在 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz 中。

可以通过使用 file:// URL 方案从本地目录读取发行版。

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--pypy-mirror pypy-mirror

设置用作下载 PyPy 安装源的 URL。

提供的 URL 将替换 https://downloads.python.org/pypy，例如在 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2 中。

可以通过使用 file:// URL 方案从本地目录读取发行版。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL

--quiet, -q

使用静默输出。

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

--reinstall, -r

重新安装最新的 Python 补丁版本（如果已安装）。

默认情况下，如果最新补丁已安装，uv 将成功退出。

是否从平台的原生证书存储加载 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 python upgrade

升级已安装的 Python 版本。

请参阅 uv python install 以查看 Python 版本安装的详细信息。

用法

uv python upgrade [OPTIONS] [TARGETS]...

参数

TARGETS

要升级的 Python 版本。

如果未提供，请求的 Python 版本将从 UV_PYTHON 环境变量中读取，然后从 .python-versions 或 .python-version 文件中读取。如果以上都没有，uv 将升级所有已安装的版本。

请参阅 uv python 了解支持的请求格式。

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--compile-bytecode, --compile

安装后将 Python 标准库编译为字节码。

默认情况下，uv 不会将 Python（.py）文件编译为字节码（__pycache__/*.pyc）；相反，编译会在首次导入模块时延迟执行。对于启动时间很重要的用例（如 CLI 应用程序和 Docker 容器），可以启用此选项，以更长的安装时间和额外的磁盘空间换取更快的启动时间。

启用后，uv 将处理 Python 版本的 stdlib 目录。它将忽略任何编译错误。

也可以通过 UV_COMPILE_BYTECODE 环境变量设置。

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

Python 安装的存储目录。

如果提供，后续操作需要设置 UV_PYTHON_INSTALL_DIR 以便 uv 发现 Python 安装。

请参阅 uv python dir 查看当前的 Python 安装目录。默认为 ~/.local/share/uv/python。

也可以通过 UV_PYTHON_INSTALL_DIR 环境变量设置。

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

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

--mirror mirror

设置用作下载 Python 安装源的 URL。

提供的 URL 将替换 https://github.com/astral-sh/python-build-standalone/releases/download，例如在 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz 中。

可以通过使用 file:// URL 方案从本地目录读取发行版。

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--pypy-mirror pypy-mirror

设置用作下载 PyPy 安装源的 URL。

提供的 URL 将替换 https://downloads.python.org/pypy，例如在 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2 中。

可以通过使用 file:// URL 方案从本地目录读取发行版。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL

--quiet, -q

使用静默输出。

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

--reinstall, -r

重新安装最新的 Python 补丁版本（如果已安装）。

默认情况下，如果最新补丁已安装，uv 将成功退出。

是否从平台的原生证书存储加载 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 python find

搜索 Python 安装。

显示 Python 可执行文件的路径。

请参阅 uv help python 了解支持的请求格式和发现行为的详细信息。

用法

uv python find [OPTIONS] [REQUEST]

参数

REQUEST

Python 请求。

请参阅 uv python 了解支持的请求格式。

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

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

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

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

--no-project, --no_workspace

避免发现项目或工作区。

否则，当未提供请求时，将使用当前目录或父目录中项目的 Python 需求。

也可以通过 UV_NO_PROJECT 环境变量设置。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL

--quiet, -q

使用静默输出。

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

--resolve-links

解析输出路径中的符号链接。

启用后，输出路径将被规范化，解析所有符号链接。

--script script

查找 Python 脚本的环境，而非当前项目

--show-version

显示将要使用的 Python 版本，而非解释器路径

--system

仅查找系统 Python 解释器。

默认情况下，uv 会报告它将使用的第一个 Python 解释器，包括活动虚拟环境中的解释器，或当前工作目录或任意父目录中虚拟环境中的解释器。

--system 选项指示 uv 跳过虚拟环境 Python 解释器，并将其搜索限制在系统路径中。

也可以通过 UV_SYSTEM_PYTHON 环境变量设置。

是否从平台的原生证书存储加载 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 python pin

锁定到特定的 Python 版本。

将锁定的 Python 版本写入 .python-version 文件，其他 uv 命令使用该文件来确定所需的 Python 版本。

如果未提供版本，uv 将查找现有的 .python-version 文件并显示当前锁定的版本。如果未找到 .python-version 文件，uv 将退出并报错。

请参阅 uv help python 了解支持的请求格式。

用法

uv python pin [OPTIONS] [REQUEST]

参数

REQUEST

Python 版本请求。

uv 支持的格式比其他读取 .python-version 文件的工具（如 pyenv）更多。如果需要与这些工具兼容，请仅使用版本号，而不是复杂的请求（如 cpython@3.10）。

如果未提供请求，将显示当前锁定的版本。

请参阅 uv python 了解支持的请求格式。

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

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

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

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL

--quiet, -q

使用静默输出。

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

--resolved

写入已解析的 Python 解释器路径，而非请求。

确保使用完全相同的解释器。

当将 .python-version 文件提交到版本控制时，通常不建议使用此选项。

--rm

移除 Python 版本锁定

是否从平台的原生证书存储加载 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 python dir

显示 uv Python 安装目录。

默认情况下，Python 安装存储在 uv 数据目录中，在 Unix 上为 $XDG_DATA_HOME/uv/python 或 $HOME/.local/share/uv/python，在 Windows 上为 %APPDATA%\uv\data\python。

Python 安装目录可以通过 $UV_PYTHON_INSTALL_DIR 覆盖。

要查看 uv 安装 Python 可执行文件的目录，请使用 --bin 标志。Python 可执行文件目录可以通过 $UV_PYTHON_BIN_DIR 覆盖。请注意，Python 可执行文件仅在启用预览模式时才会安装。

用法

uv python dir [OPTIONS]

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--bin

显示 uv python 将安装 Python 可执行文件的目录。

请注意，此目录仅在启用预览模式安装 Python 时使用。

Python 可执行文件目录根据 XDG 标准确定，并派生自以下环境变量，按优先级顺序排列：

$UV_PYTHON_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

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

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

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--quiet, -q

使用静默输出。

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

是否从平台的原生证书存储加载 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 python uninstall

卸载 Python 版本

用法

uv python uninstall [OPTIONS] <TARGETS>...

参数

TARGETS

要卸载的 Python 版本。

请参阅 uv python 了解支持的请求格式。

选项

--all

卸载所有由 uv 管理的 Python 版本

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

Python 的安装目录

也可以通过 UV_PYTHON_INSTALL_DIR 环境变量设置。

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

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

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

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

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

例如，旋转器或进度条。

禁用 Python 的自动下载。

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

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

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--quiet, -q

使用静默输出。

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

是否从平台的原生证书存储加载 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 python update-shell

确保 Python 可执行文件目录位于 PATH 中。

如果 Python 可执行文件目录不在 PATH 中，uv 将尝试将其添加到相关的 shell 配置文件中。

如果 shell 配置文件已包含将可执行文件目录添加到路径的片段，但该目录不在 PATH 中，uv 将退出并报错。

Python 可执行文件目录根据 XDG 标准确定，可以通过 uv python dir --bin 获取。

用法

uv python update-shell [OPTIONS]

选项

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

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

可以多次提供。

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

警告：此列表中的主机将不会通过系统的证书存储进行验证。仅在安全的网络中使用 --allow-insecure-host，并确保来源可信，因为它会绕过 SSL 验证，可能使您面临中间人攻击（MITM）的风险。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

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

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

也可以通过 UV_CACHE_DIR 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

--config-file config-file

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

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

也可以通过 UV_CONFIG_FILE 环境变量设置。

--directory directory

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

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

请参阅 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--help, -h

显示此命令的简明帮助

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

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

也可以通过 UV_NO_CACHE 环境变量设置。

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

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

也可以通过 UV_NO_CONFIG 环境变量设置。

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

例如，旋转器或进度条。

--project project

在指定目录中发现项目。

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

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

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

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

也可以通过 UV_PROJECT 环境变量设置。

--quiet, -q

使用静默输出。

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