Uv Run

---
created: 2025-12-16
modified: 2026-05-09
reviewed: 2026-04-25
name: uv-run
description: Run Python scripts with uv (PEP 723 inline deps, --with for one-off deps). Use when running scripts without venv activation or needing one-off dependencies.
user-invocable: false
allowed-tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, Edit, Write, NotebookEdit, Bash
---

# UV Run

Run Python scripts with uv - no manual venv activation needed.

## When to Use This Skill

| Use this skill when... | Use a focused sibling instead when... |
|---|---|
| Running a one-off script with `uv run script.py` and no project context | Adding a long-lived dependency to a project — use uv-project-management |
| Embedding PEP 723 inline metadata or `--with` deps into a self-contained script | Installing a global CLI tool (`uv tool install` / `uvx`) — use uv-tool-management |
| Executing project commands inside the project venv without manual activation | Authoring the project's pyproject.toml or lockfile — use uv-project-management |

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

## Essential Commands

### Running Scripts

```bash
# 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
```

### Temporary Dependencies

Add dependencies for a single run without modifying project:

```bash
# 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
```

### Inline Script Dependencies (PEP 723)

Create self-contained scripts with embedded dependencies:

```python
#!/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())
```

Run directly:
```bash
uv run script.py

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

### Managing Script Dependencies

```bash
# 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
```

### Ephemeral Tool Execution (uvx)

Run CLI tools without installation:

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

# With specific version
uvx ruff@0.1.0 check .

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

## Shebang Patterns

### Self-Contained Executable Script

```python
#!/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()
```

### Script with Python Version Requirement

```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
```

## When to Use Each Pattern

| Scenario | Approach |
|----------|----------|
| Quick one-off task | `uv run --with pkg script.py` |
| Reusable script | Inline deps (PEP 723) |
| Shareable utility | PEP 723 + shebang |
| Team collaboration | Inline deps + `uv lock --script` |
| Run CLI tool once | `uvx tool` |
| Project scripts | `uv run` (uses project deps) |

## uvx vs 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
# Run a tool (CLI application)
uvx httpie https://api.github.com

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

## Profiling and Debugging

```bash
# 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
```

## See Also

- **uv-project-management** - Project dependencies and lockfiles
- **uv-tool-management** - Installing CLI tools globally
- **python-development** - Core Python language patterns

## References

- Official docs: https://docs.astral.sh/uv/guides/scripts/
- PEP 723: https://peps.python.org/pep-0723/
- Tools: https://docs.astral.sh/uv/guides/tools/