uv-run

# UV Run

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

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