Back to Details

uv-run

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UV Run

UV Run

Run Python scripts with uv - no manual venv activation needed.
使用uv运行Python脚本，无需手动激活虚拟环境。

Core Capabilities

核心功能

  • Direct execution: 
    uv run script.py
    handles environment automatically
  • Temporary dependencies: 
    uv run --with requests script.py
    for one-off needs
  • Inline dependencies: PEP 723 metadata blocks for self-contained scripts
  • Ephemeral tools: 
    uvx tool
    runs CLI tools without installation
  • 直接执行：
    uv run script.py
    会自动处理环境
  • 临时依赖：
    uv run --with requests script.py
    可满足一次性依赖需求
  • 内联依赖：支持PEP 723元数据块，实现自包含脚本
  • 临时工具：
    uvx tool
    无需安装即可运行CLI工具

Essential Commands

常用命令

Running Scripts

运行脚本

bash
undefined
bash
undefined

Run script (uv manages environment automatically)

Run script (uv manages environment automatically)

uv run script.py
uv run script.py

Run with arguments

Run with arguments

uv run script.py --input data.csv --output results.json
uv run script.py --input data.csv --output results.json

Run a specific module

Run a specific module

uv run -m http.server 8000
uv run -m http.server 8000

Run with specific Python version

Run with specific Python version

uv run --python 3.12 script.py
undefined
uv run --python 3.12 script.py
undefined

Temporary Dependencies

临时依赖

Add dependencies for a single run without modifying project:
bash
undefined
单次运行时添加依赖，无需修改项目配置：
bash
undefined

Single dependency

Single dependency

uv run --with requests fetch_data.py
uv run --with requests fetch_data.py

Multiple dependencies

Multiple dependencies

uv run --with requests --with rich api_client.py
uv run --with requests --with rich api_client.py

Version constraints

Version constraints

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

Combine with project dependencies

Combine with project dependencies

uv run --with pytest-benchmark pytest # Add benchmark to existing pytest
undefined
uv run --with pytest-benchmark pytest # Add benchmark to existing pytest
undefined

Inline Script Dependencies (PEP 723)

内联脚本依赖（PEP 723）

Create self-contained scripts with embedded dependencies:
python
#!/usr/bin/env -S uv run --script
通过内嵌依赖创建自包含脚本：
python
#!/usr/bin/env -S uv run --script

/// script

/// script

requires-python = ">=3.11"

requires-python = ">=3.11"

dependencies = [

dependencies = [

"requests>=2.31",

"requests>=2.31",

"rich>=13.0",

"rich>=13.0",

]

]

///

///

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

Run directly:
```bash
uv run script.py
import requests from rich import print
response = requests.get("https://api.github.com") print(response.json())

直接运行即可：
```bash
uv run script.py

Or make executable:

Or make executable:

chmod +x script.py ./script.py
undefined
chmod +x script.py ./script.py
undefined

Managing Script Dependencies

管理脚本依赖

bash
undefined
bash
undefined

Initialize script with metadata

Initialize script with metadata

uv init --script example.py --python 3.12
uv init --script example.py --python 3.12

Add dependency to script

Add dependency to script

uv add --script example.py requests rich
uv add --script example.py requests rich

Lock script dependencies for reproducibility

Lock script dependencies for reproducibility

uv lock --script example.py
undefined
uv lock --script example.py
undefined

Ephemeral Tool Execution (uvx)

临时工具执行（uvx）

Run CLI tools without installation:
bash
undefined
无需安装即可运行CLI工具：
bash
undefined

Run tool once

Run tool once

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

With specific version

With specific version

uvx ruff@0.1.0 check .
uvx ruff@0.1.0 check .

uvx is shorthand for:

uvx is shorthand for:

uv tool run pycowsay "Hello"
undefined
uv tool run pycowsay "Hello"
undefined

Shebang Patterns

Shebang使用模式

Self-Contained Executable Script

自包含可执行脚本

python
#!/usr/bin/env -S uv run --script
python
#!/usr/bin/env -S uv run --script

/// script

/// script

dependencies = ["click", "rich"]

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()
undefined
import click from rich import print
@click.command() @click.argument('name') def hello(name): print(f"[green]Hello, {name}![/green]")
if name == "main": hello()
undefined

Script with Python Version Requirement

指定Python版本要求的脚本

python
#!/usr/bin/env -S uv run --script --python 3.12
python
#!/usr/bin/env -S uv run --script --python 3.12

/// script

/// script

requires-python = ">=3.12"

requires-python = ">=3.12"

dependencies = ["httpx"]

dependencies = ["httpx"]

///

///

import httpx
import httpx

Uses Python 3.12+ features

Uses Python 3.12+ features

undefined
undefined

When to Use Each Pattern

各模式适用场景

ScenarioApproach
Quick one-off task
uv run --with pkg script.py
Reusable scriptInline deps (PEP 723)
Shareable utilityPEP 723 + shebang
Team collaborationInline deps + 
uv lock --script
Run CLI tool once
uvx tool
Project scripts
uv run
(uses project deps)
场景方案
快速一次性任务
uv run --with pkg script.py
可复用脚本内联依赖（PEP 723）
可分享的工具脚本PEP 723 + shebang
团队协作场景内联依赖 + 
uv lock --script
单次运行CLI工具
uvx tool
项目脚本
uv run
（使用项目依赖）

uvx vs uv run --with

uvx 与 uv run --with 的区别

  • uvx tool
    : Run a CLI tool without installation (e.g., 
    uvx ruff check .
    )
  • uv run --with pkg
    : Run a script with temporary dependencies (e.g., 
    uv run --with requests script.py
    )
bash
undefined
  • uvx tool
    ：无需安装运行CLI工具（例如 
    uvx ruff check .
    ）
  • uv run --with pkg
    ：带临时依赖运行脚本（例如 
    uv run --with requests script.py
    ）
bash
undefined

Run a tool (CLI application)

Run a tool (CLI application)

uvx httpie https://api.github.com
uvx httpie https://api.github.com

Run a script with dependencies

Run a script with dependencies

uv run --with httpx api_test.py
undefined
uv run --with httpx api_test.py
undefined

Profiling and Debugging

性能分析与调试

bash
undefined
bash
undefined

CPU profiling

CPU性能分析

uv run python -m cProfile -s cumtime script.py | head -20
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
uv run --with line-profiler kernprof -l -v script.py

Memory profiling

内存分析

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

Real-time profiling (ephemeral tool)

实时性能分析（临时工具）

uvx py-spy top -- python script.py
uvx py-spy top -- python script.py

Quick profiling

快速性能分析

uv run --with scalene python -m scalene script.py
undefined
uv run --with scalene python -m scalene script.py
undefined

See Also

相关内容

  • uv-project-management - Project dependencies and lockfiles
  • uv-tool-management - Installing CLI tools globally
  • python-development - Core Python language patterns
  • uv-project-management - 项目依赖与锁文件
  • uv-tool-management - 全局安装CLI工具
  • python-development - Python核心语言使用模式

References

参考资料