uv-run

UV Run

使用 uv 运行 Python 脚本，无需手动激活 venv。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用更专注的同类技能……
使用 uv run script.py 运行一次性脚本，且没有项目上下文	为项目添加长期依赖项 — 使用 uv-project-management
在独立脚本中嵌入 PEP 723 内联元数据或 --with 依赖项	安装全局 CLI 工具（uv tool install / uvx）— 使用 uv-tool-management
在项目 venv 中执行项目命令，无需手动激活	编写项目的 pyproject.toml 或锁文件 — 使用 uv-project-management

核心功能

• 直接执行：uv run script.py 会自动处理环境
• 临时依赖项：使用 uv run --with requests script.py 满足一次性需求
• 内联依赖项：通过 PEP 723 元数据块创建独立脚本
• 临时工具：uvx tool 可运行 CLI 工具，无需安装

基本命令

运行脚本

# Run script (uv manages environment automatically)
uv run script.py

# Run with arguments
uv run script.py --input data.csv --output results.json

# Run a specific module
uv run -m http.server 8000

# Run with specific Python version
uv run --python 3.12 script.py

临时依赖项

为单次运行添加依赖项，不修改项目：

# Single dependency
uv run --with requests fetch_data.py

# Multiple dependencies
uv run --with requests --with rich api_client.py

# Version constraints
uv run --with 'requests>=2.31' --with 'rich>12,<14' script.py

# Combine with project dependencies
uv run --with pytest-benchmark pytest  # Add benchmark to existing pytest

内联脚本依赖项（PEP 723）

创建嵌入依赖项的独立脚本：

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests>=2.31",
#   "rich>=13.0",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

直接运行：

uv run script.py

# Or make executable:
chmod +x script.py
./script.py

管理脚本依赖项

# Initialize script with metadata
uv init --script example.py --python 3.12

# Add dependency to script
uv add --script example.py requests rich

# Lock script dependencies for reproducibility
uv lock --script example.py

临时工具执行（uvx）

运行 CLI 工具，无需安装：

# Run tool once
uvx pycowsay "Hello from uv!"
uvx httpie https://api.github.com
uvx ruff check .

# With specific version
uvx [email protected] check .

# uvx is shorthand for:
uv tool run pycowsay "Hello"

Shebang 模式

独立可执行脚本

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["click", "rich"]
# ///

import click
from rich import print

@click.command()
@click.argument('name')
def hello(name):
    print(f"[green]Hello, {name}![/green]")

if __name__ == "__main__":
    hello()

指定 Python 版本的脚本

#!/usr/bin/env -S uv run --script --python 3.12
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

import httpx
# Uses Python 3.12+ features

各模式的适用场景

场景	方式
快速的一次性任务	uv run --with pkg script.py
可复用脚本	内联依赖项（PEP 723）
可分享的实用工具	PEP 723 + shebang
团队协作	内联依赖项 + uv lock --script
运行一次 CLI 工具	uvx tool
项目脚本	uv run（使用项目依赖项）

uvx 与 uv run --with 的区别

• uvx tool：运行 CLI 工具，无需安装（例如：uvx ruff check .）
• uv run --with pkg：运行带有临时依赖项的脚本（例如：uv run --with requests script.py）

# Run a tool (CLI application)
uvx httpie https://api.github.com

# Run a script with dependencies
uv run --with httpx api_test.py

性能分析与调试

# CPU profiling
uv run python -m cProfile -s cumtime script.py | head -20

# Line-by-line profiling (temporary dependency)
uv run --with line-profiler kernprof -l -v script.py

# Memory profiling
uv run --with memory-profiler python -m memory_profiler script.py

# Real-time profiling (ephemeral tool)
uvx py-spy top -- python script.py

# Quick profiling
uv run --with scalene python -m scalene script.py

另请参阅

• uv-project-management - 项目依赖项和锁文件
• uv-tool-management - 全局安装 CLI 工具
• python-development - Python 语言核心模式

参考资料

• 官方文档：https://docs.astral.sh/uv/guides/scripts/
• PEP 723：https://peps.python.org/pep-0723/
• 工具：https://docs.astral.sh/uv/guides/tools/