在项目中运行命令

在处理项目时，项目会被安装到 .venv 中的虚拟环境里。默认情况下，这个环境与当前 shell 是隔离的，所以需要项目支持的调用（例如 python -c "import example"）会失败。相反，应使用 uv run 在项目环境中运行命令：

$ uv run python -c "import example"

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

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

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

$ # 运行一个需要项目可用的 `bash` 脚本
$ 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

# /// 脚本

# 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 脚本

支持旧版 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 信号转发到子进程。由于 shell 在按下 Ctrl-C 时会将 SIGINT 发送到前台进程组，所以只有在多次看到 SIGINT 信号，或者子进程组与 uv 的进程组不同时，uv 才会将 SIGINT 转发到子进程。

在 Windows 系统上，这些概念并不适用，uv 会忽略 Ctrl-C 事件，将处理工作交给子进程，以便子进程能够正常退出。