python-runner

Running Python Scripts with uv

Execute Python scripts with automatic, isolated dependency management. No manual environment setup required.

Quick Reference

# Check if uv is available
uv --version

# Run script without dependencies
uv run script.py

# Run script with dependencies (installed automatically)
uv run --with pandas --with requests script.py

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

If uv is not installed, see references/install-uv.md.

Recommended Approach: Inline Dependencies

Embed dependencies directly in the script so it's self-contained and reproducible:

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "pandas",
#   "requests",
# ]
# ///

import pandas as pd
import requests

# ... rest of script

Then run with just:

uv run script.py

uv automatically creates an isolated environment with the declared dependencies.

Adding Dependencies to Scripts

Use uv add --script to add dependencies to an existing script:

# Add single dependency
uv add --script script.py pandas

# Add multiple with version constraints
uv add --script script.py 'requests<3' 'rich>=13'

This inserts/updates the # /// script metadata block at the top of the file.

Common Patterns

Data analysis script

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "pandas",
#   "openpyxl",  # for Excel support
# ]
# ///

import pandas as pd

df = pd.read_excel("data.xlsx")
print(df.describe())

Web scraping script

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "requests",
#   "beautifulsoup4",
#   "lxml",
# ]
# ///

import requests
from bs4 import BeautifulSoup

resp = requests.get("https://example.com")
soup = BeautifulSoup(resp.text, "lxml")

PDF processing script

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "pdfplumber",
#   "pandas",
# ]
# ///

import pdfplumber
import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        tables = page.extract_tables()

Command Options

Option	Purpose	Example
--with pkg	Add dependency for this run only	uv run --with rich script.py
--python X.Y	Use specific Python version	uv run --python 3.11 script.py
--no-project	Ignore pyproject.toml in directory	uv run --no-project script.py

Passing Arguments to Scripts

Arguments after the script name pass through to the script:

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

In the script:

import sys
print(sys.argv)  # ['script.py', 'input.csv', '--output', 'results.json']

Troubleshooting

"uv: command not found" → uv not installed. See references/install-uv.md

Module not found errors → Add missing package to dependencies block or use --with

Wrong Python version → Specify version: uv run --python 3.11 script.py → Or add requires-python to script metadata

Script in a project directory picks up wrong dependencies → Use --no-project flag before script name