uv run 可自动运行 python 脚本并管理依赖：支持项目环境、pep 723 单文件脚本、临时追加依赖（--with）及任意 cli 工具，无需手动激活虚拟环境。

你想在不手动激活虚拟环境的前提下，直接运行 Python 脚本并自动满足其依赖——uv run 就是为此设计的核心命令，它会自动发现项目环境或为脚本创建隔离环境，省去 source .venv/bin/activate 的冗余步骤。

运行项目内的 Python 脚本

确保当前目录下存在 pyproject.toml 或 .venv 目录，uv 会自动识别项目环境。

执行 uv run script.py，uv 会使用项目虚拟环境中的 Python 解释器运行该脚本。

如果脚本需要额外依赖（如 requests），但未在 pyproject.toml 中声明，uv run 会报错退出——【必须先用 uv add requests 声明依赖】，否则无法解析导入。

这一步不支持隐式安装；uv 不会在运行时自动推断并安装缺失包，它严格遵循锁文件或 pyproject.toml 中的依赖声明。

运行带内联依赖的单文件脚本（PEP 723）

方法一：在脚本顶部添加 PEP 723 元数据块

用编辑器打开 your_script.py，在第一行写入：

```python
# /// script
# dependencies = ["rich", "httpx"]
# ///

print("Hello with rich and httpx!")

保存后执行 uv run your_script.py，uv 会自动创建临时环境并安装 rich 和 httpx。

注意：元数据块必须紧贴文件开头，且仅允许一个 /// script 区块；多于一个会导致解析失败。

运行脚本并临时追加依赖

第一步：确认脚本本身可独立运行（无缺失 import 报错）

第二步：执行 uv run --with pytest --with black your_script.py

uv 会基于当前项目环境派生一个新环境，在其中安装 pytest 和 black 后再运行 your_script.py。

这个派生环境只存在一次执行生命周期，不会写入 pyproject.toml，也不会影响 .venv。

若 your_script.py 本身依赖 pandas，但项目未声明，此时仍会失败——【--with 只追加，不补全基础依赖】。

运行非 Python 脚本或 CLI 工具

uv run 支持任何可执行命令，不限于 Python。

例如 uv run bash build.sh 在 Linux/macOS 上执行 shell 脚本；uv run cmd /c build.bat 在 Windows 上执行批处理。

只要命令存在于系统 PATH 或当前环境 Scripts/bin 目录中，uv run 都能调用。

这相当于把整个虚拟环境的 bin/Scripts 目录临时加入子进程 PATH，无需手动配置。