在项目中运行命令

在项目中使用时，它会安装到 .venv 的虚拟环境中。默认情况下，此环境与当前 shell 隔离，因此需要项目的调用（例如，python -c "import example"）将会失败。而是使用 uv run 在项目环境中运行命令

$ uv run python -c "import example"

使用 run 时，uv 将确保项目环境在运行给定命令之前是最新的。

给定的命令可以由项目环境提供，也可以存在于项目环境之外，例如。

$ # Presuming the project provides `example-cli`
$ uv run example-cli foo

$ # Running a `bash` script that requires the project to be available
$ uv run bash scripts/foo.sh

请求额外的依赖项

每次调用都可以请求额外的依赖项或不同版本的依赖项。

--with 选项用于为调用包含依赖项，例如，请求 httpx 的不同版本

$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
0.26.0
$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
0.25.0

无论项目的要求如何，都会遵守请求的版本。例如，即使项目需要 httpx==0.24.0，上面的输出也是相同的。

运行脚本

声明内联元数据的脚本会自动在与项目隔离的环境中执行。有关更多详细信息，请参阅脚本指南。

例如，给定一个脚本

example.py

# /// script
# dependencies = [
#   "httpx",
# ]
# ///

import httpx

resp = httpx.get("https://peps.pythonlang.cn/api/peps.json")
data = resp.json()
print([(k, v["title"]) for k, v in data.items()][:10])

调用 uv run example.py 将在隔离于项目的环境中运行，仅列出给定的依赖项。

旧版 Windows 脚本

支持旧版 setuptools 脚本。这些类型的脚本是由 setuptools 安装在 .venv\Scripts 中的附加文件。

目前仅支持带有 .ps1、.cmd 和 .bat 扩展名的旧版脚本。

例如，下面是一个运行命令提示符脚本的示例。

$ uv run --with nuitka==2.6.7 -- nuitka.cmd --version

此外，您无需指定扩展名。 uv 将自动查找以 .ps1、.cmd 和 .bat 结尾的文件，并按执行顺序排列。

$ uv run --with nuitka==2.6.7 -- nuitka --version

信号处理

uv 不会将进程控制权让给生成的命令，以便在发生故障时提供更好的错误消息。因此，uv 负责将一些信号转发到请求命令运行的子进程。

在 Unix 系统上，uv 会将 SIGINT 和 SIGTERM 转发到子进程。由于终端在 Ctrl-C 时将 SIGINT 发送到前台进程组，因此 uv 仅在 SIGINT 发送多次或子进程组与 uv 的进程组不同时才会将 SIGINT 转发到子进程。

在 Windows 上，这些概念不适用，uv 会忽略 Ctrl-C 事件，并将处理权交给子进程，以便它可以干净地退出。