3.4.4 运行命令

原文链接: https://docs.astral.sh/uv/concepts/projects/run/

3.4.4 运行命令

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

1

$ uv run python -c "import example"

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

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

1
2
3
4
5

$ # 假设项目提供了 `example-cli`
$ uv run example-cli foo

$ # 运行一个需要项目可用的 `bash` 脚本
$ uv run bash scripts/foo.sh

请求额外的依赖

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

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

1
2
3
4

$ 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，上面的输出也保持不变。

运行脚本

声明了内联元数据的脚本会自动在独立于项目的环境中执行。更多细节请参阅脚本指南。

例如，给定如下脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# example.py
# /// script
# dependencies = [
#   "httpx",
# ]
# ///

import httpx

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

调用 uv run example.py 时会与项目隔离运行，只使用列出��给定依赖。

Windows 上的旧式脚本

uv 支持旧式 setuptools 脚本。这类脚本是 setuptools 安装在 .venv\Scripts 中的额外文件。

目前只支持扩展名为 .ps1、.cmd 和 .bat 的旧式脚本。

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

1

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

此外，你无需指定扩展名。uv 会自动按 .ps1、.cmd、.bat 的顺序为你查找相应文件。

1

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

信号处理

为了在失败时提供更好的错误信息，uv 不会把进程控制权交给所生成的命令。因此，uv 负责把部分信号转发给所请求命令运行所在的子进程。

在 Unix 系统上，uv 会把大多数信号转发给子进程（SIGKILL、SIGCHLD、SIGIO 和 SIGPOLL 除外）。由于终端在按下 Ctrl-C 时会向前台进程组发送 SIGINT，uv 只在 SIGINT 被发送多次，或子进程组与 uv 的进程组不同时，才把它转发给子进程。

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