uv run

运行命令或脚本。

确保命令在 Python 环境中运行。

当与 .py 结尾的文件或 HTTP(S) URL 一起使用时，该文件将被视为脚本并使用 Python 解释器运行，即 uv run file.py 等价于 uv run python file.py。对于 URL，脚本会在执行前临时下载。如果脚本包含内联依赖元数据，这些依赖将被安装到一个隔离的临时环境中。当与 - 一起使用时，将从 stdin 读取输入并将其视为 Python 脚本。

在项目中使用时，项目环境将在调用命令之前创建并更新。

在项目外部使用时，如果在当前目录或父目录中找到虚拟环境，命令将在该环境中运行。否则，命令将在所发现解释器的环境中运行。

默认情况下，项目或工作区从当前工作目录中发现。但是，当使用 --preview-features target-workspace-discovery 时，项目或工作区将从目标脚本的目录中发现。

命令（或脚本）之后的参数不会被解释为 uv 的参数。所有 uv 选项必须在命令之前提供，例如 uv run --verbose foo。可以使用 -- 将命令与 uv 选项分开以增加清晰度，例如 uv run --python 3.12 -- python。

Usage

uv run [OPTIONS] [COMMAND]

Options

--active

优先使用活动虚拟环境，而非项目的虚拟环境。

如果项目虚拟环境已处于活动状态或没有活动虚拟环境，此选项无效。

--all-extras

包含所有可选依赖。

此选项仅在项目中运行时可用。

--all-groups

包含所有依赖组中的依赖。

可使用 --no-group 排除特定组。

--all-packages

在安装所有工作区成员的情况下运行命令。

工作区环境（.venv）将更新以包含所有工作区成员。

通过 --extra、--group 或相关选项指定的任何 extras 或组将应用于所有工作区成员。

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

允许与主机的非安全连接。

可多次提供。

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

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

也可通过 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 将处理整个 site-packages 目录（包括当前操作未修改的包）以保持一致性。与 pip 类似，它也会忽略错误。

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

--config-file config-file

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

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

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

--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 标志指定的所有其他索引。

也可通过 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

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

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

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

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

--env-file env-file

从 .env 文件加载环境变量。

可多次提供，后续文件中的值将覆盖先前文件中定义的值。

也可通过 UV_ENV_FILE 环境变量设置。

--exact

执行精确同步，移除多余的包。

启用后，uv 将从环境中移除任何多余的包。默认情况下，uv run 仅进行满足需求所需的最小更改。

--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 小时（例如，忽略 DST 转换）。不允许使用日历单位（如月和年）。

也可通过 UV_EXCLUDE_NEWER 环境变量设置。

--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 小时（例如，忽略 DST 转换）。不允许使用日历单位（如月和年）。

可为不同包多次提供。

--extra extra

包含来自指定 extra 名称的可选依赖。

可多次提供。

此选项仅在项目中运行时可用。

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

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

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

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

也可通过 UV_EXTRA_INDEX_URL 环境变量设置。

--find-links, -f find-links

搜索候选分发包的位置，作为注册表索引中已找到项的补充。

如果是路径，目标必须是一个目录，其中包含 wheel 文件（.whl）或源码分发包（例如 .tar.gz 或 .zip）作为顶层内容。

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

也可通过 UV_FIND_LINKS 环境变量设置。

--fork-strategy fork-strategy

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

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

在 fewest 模式下，uv 将最小化每个包的选择版本数，优先选择与更广泛的受支持 Python 版本或平台兼容的旧版本。

也可通过 UV_FORK_STRATEGY 环境变量设置。

可选值：

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

--frozen

在不更新 uv.lock 文件的情况下运行 [env: UV_FROZEN=]

不检查锁文件是否为最新版本，而是将锁文件中的版本作为唯一真实来源。如果锁文件缺失，uv 将退出并报错。如果 pyproject.toml 包含尚未纳入锁文件的依赖更改，这些更改将不会体现在环境中。

--group group

包含来自指定依赖组的依赖。

可多次提供。

--gui-script

将给定路径作为 Python GUI 脚本运行。

使用 --gui-script 将尝试将路径解析为 PEP 723 脚本，并使用 pythonw.exe 运行，无论其扩展名如何。仅适用于 Windows。

--help, -h

显示此命令的简明帮助

--index index

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

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

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

索引名称不支持作为值。相对路径必须通过 ./ 或 ../（Unix 上）或 .\\、..\\、./ 或 ../（Windows 上）与索引名称区分。

也可通过 UV_INDEX 环境变量设置。

--index-strategy index-strategy

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

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

也可通过 UV_INDEX_STRATEGY 环境变量设置。

可选值：

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 标志指定的所有其他索引。

也可通过 UV_INDEX_URL 环境变量设置。

--isolated

在隔离的虚拟环境中运行命令 [env: UV_ISOLATED=]

通常，项目环境会为性能而复用。此选项强制为项目使用全新的环境，强制依赖项与需求声明之间严格隔离。

项目仍会使用可编辑安装。

当与 --with 或 --with-requirements 一起使用时，额外的依赖仍将在第二个环境中分层叠加。

--keyring-provider keyring-provider

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

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

默认为 disabled。

也可通过 UV_KEYRING_PROVIDER 环境变量设置。

可选值：

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

--link-mode link-mode

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

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

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

也可通过 UV_LINK_MODE 环境变量设置。

可选值：

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

--locked

断言 uv.lock 将保持不变 [env: UV_LOCKED=]

要求锁文件是最新的。如果锁文件缺失或需要更新，uv 将退出并报错。

--managed-python

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

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

--module, -m

运行 Python 模块。

等价于 python -m <module>。

--no-binary

不安装预构建的 wheel。

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

也可通过 UV_NO_BINARY 环境变量设置。

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

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

--no-build

不构建源码分发包。

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

也可通过 UV_NO_BUILD 环境变量设置。

--no-build-isolation

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

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

也可通过 UV_NO_BUILD_ISOLATION 环境变量设置。

--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

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

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

--no-config

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

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

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

--no-default-groups

忽略默认依赖组。

uv 默认包含 tool.uv.default-groups 中定义的组。此选项禁用该行为，但仍可通过 --group 包含特定组。

也可通过 UV_NO_DEFAULT_GROUPS 环境变量设置。

--no-dev

禁用开发依赖组 [env: UV_NO_DEV=]

此选项是 --no-group dev 的别名。参见 --no-default-groups 以禁用所有默认组。

此选项仅在项目中运行时可用。

--no-editable

将所有可编辑依赖（包括项目和工作区成员）以非可编辑方式安装 [env: UV_NO_EDITABLE=]

--no-editable-package no-editable-package

将指定的可编辑包以非可编辑方式安装

--no-env-file

避免从 .env 文件读取环境变量 [env: UV_NO_ENV_FILE=]

--no-extra no-extra

如果提供了 --all-extras，则排除指定的可选依赖。

可多次提供。

--no-group no-group

禁用指定的依赖组 [env: UV_NO_GROUP=]

此选项始终优先于默认组、--all-groups 和 --group。

可多次提供。

--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-project, --no_workspace

避免发现项目或工作区。

不在当前目录和父目录中搜索项目，而是在由 --with 需求填充的隔离临时环境中运行。

如果虚拟环境处于活动状态或在当前或父目录中找到，它将像没有项目或工作区一样被使用。

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

--no-python-downloads

禁用 Python 的自动下载。

--no-sources

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

也可通过 UV_NO_SOURCES 环境变量设置。

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

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

--no-sync

避免同步虚拟环境 [env: UV_NO_SYNC=]

隐含 --frozen，因为项目依赖将被忽略（即锁文件不会更新，因为环境无论如何都不会同步）。

--offline

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

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

--only-dev

仅包含开发依赖组。

项目及其依赖将被省略。

此选项是 --only-group dev 的别名。隐含 --no-default-groups。

--only-group only-group

仅包含来自指定依赖组的依赖。

项目及其依赖将被省略。

可多次提供。隐含 --no-default-groups。

--package package

在工作区中的特定包中运行命令。

如果工作区成员不存在，uv 将退出并报错。

--prerelease prerelease

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

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

也可通过 UV_PRERELEASE 环境变量设置。

可选值：

disallow：禁止所有预发布版本
allow：允许所有预发布版本
if-necessary：如果包的所有版本都是预发布版本，则允许预发布版本
explicit：允许版本需求中带有显式预发布标记的第一方包的预发布版本
if-necessary-or-explicit：如果包的所有版本都是预发布版本，或包的版本需求中带有显式预发布标记，则允许预发布版本

--project project

在给定目录中发现项目。

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

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

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

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

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

--python, -p python

用于运行环境的 Python 解释器。

如果解释器请求由已发现的环境满足，则将使用该环境。

参见 uv python 查看支持的请求格式。

也可通过 UV_PYTHON 环境变量设置。

--python-platform python-platform

应为其安装需求的目标平台。

表示为"目标三元组"，一个描述目标平台的字符串，包含其 CPU、供应商和操作系统名称，如 x86_64-unknown-linux-gnu 或 aarch64-apple-darwin。

当目标为 macOS（Darwin）时，默认最低版本为 13.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如 14.0。

当目标为 iOS 时，默认最低版本为 13.0。使用 IPHONEOS_DEPLOYMENT_TARGET 指定不同的最低版本，例如 14.0。

当目标为 Android 时，默认最低 Android API 级别为 24。使用 ANDROID_API_LEVEL 指定不同的最低版本，例如 26。

警告：指定后，uv 将选择与目标平台兼容的 wheel；因此，安装的分发包可能与当前平台不兼容。反之，任何从源码构建的分发包可能与目标平台不兼容，因为它们将为当前平台构建。--python-platform 选项适用于高级用例。

可选值：

windows：x86_64-pc-windows-msvc 的别名，Windows 的默认目标
linux：x86_64-unknown-linux-gnu 的别名，Linux 的默认目标
macos：aarch64-apple-darwin 的别名，macOS 的默认目标
x86_64-pc-windows-msvc：64 位 x86 Windows 目标
aarch64-pc-windows-msvc：ARM64 Windows 目标
i686-pc-windows-msvc：32 位 x86 Windows 目标
x86_64-unknown-linux-gnu：x86 Linux 目标。等价于 x86_64-manylinux_2_28
aarch64-apple-darwin：基于 ARM 的 macOS 目标，用于 Apple Silicon 设备
x86_64-apple-darwin：x86 macOS 目标
aarch64-unknown-linux-gnu：ARM64 Linux 目标。等价于 aarch64-manylinux_2_28
aarch64-unknown-linux-musl：ARM64 Linux 目标
x86_64-unknown-linux-musl：x86_64 Linux 目标
riscv64-unknown-linux：RISCV64 Linux 目标
x86_64-manylinux2014：manylinux2014 平台的 x86_64 目标。等价于 x86_64-manylinux_2_17
x86_64-manylinux_2_17：manylinux_2_17 平台的 x86_64 目标
x86_64-manylinux_2_28：manylinux_2_28 平台的 x86_64 目标
x86_64-manylinux_2_31：manylinux_2_31 平台的 x86_64 目标
x86_64-manylinux_2_32：manylinux_2_32 平台的 x86_64 目标
x86_64-manylinux_2_33：manylinux_2_33 平台的 x86_64 目标
x86_64-manylinux_2_34：manylinux_2_34 平台的 x86_64 目标
x86_64-manylinux_2_35：manylinux_2_35 平台的 x86_64 目标
x86_64-manylinux_2_36：manylinux_2_36 平台的 x86_64 目标
x86_64-manylinux_2_37：manylinux_2_37 平台的 x86_64 目标
x86_64-manylinux_2_38：manylinux_2_38 平台的 x86_64 目标
x86_64-manylinux_2_39：manylinux_2_39 平台的 x86_64 目标
x86_64-manylinux_2_40：manylinux_2_40 平台的 x86_64 目标
aarch64-manylinux2014：manylinux2014 平台的 ARM64 目标。等价于 aarch64-manylinux_2_17
aarch64-manylinux_2_17：manylinux_2_17 平台的 ARM64 目标
aarch64-manylinux_2_28：manylinux_2_28 平台的 ARM64 目标
aarch64-manylinux_2_31：manylinux_2_31 平台的 ARM64 目标
aarch64-manylinux_2_32：manylinux_2_32 平台的 ARM64 目标
aarch64-manylinux_2_33：manylinux_2_33 平台的 ARM64 目标
aarch64-manylinux_2_34：manylinux_2_34 平台的 ARM64 目标
aarch64-manylinux_2_35：manylinux_2_35 平台的 ARM64 目标
aarch64-manylinux_2_36：manylinux_2_36 平台的 ARM64 目标
aarch64-manylinux_2_37：manylinux_2_37 平台的 ARM64 目标
aarch64-manylinux_2_38：manylinux_2_38 平台的 ARM64 目标
aarch64-manylinux_2_39：manylinux_2_39 平台的 ARM64 目标
aarch64-manylinux_2_40：manylinux_2_40 平台的 ARM64 目标
aarch64-linux-android：ARM64 Android 目标
x86_64-linux-android：x86_64 Android 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12。参见 https://pyodide.org/en/stable/development/abi/312.html
wasm32-pyodide2025：使用 Pyodide 2025 平台的 wasm32 目标。适用于 Python 3.13。参见 https://pyodide.org/en/stable/development/abi/313.html
arm64-apple-ios：iOS 设备的 ARM64 目标
arm64-apple-ios-simulator：iOS 模拟器的 ARM64 目标
x86_64-apple-ios-simulator：iOS 模拟器的 x86_64 目标

--quiet, -q