uv Scripts Guide

All ADW scripts run via uv run. This guide explains how uv manages dependencies for the ADW system and how to use it for your own scripts.

Why uv

uv automatically manages virtual environments. Instead of:

python -m venv venv
source venv/bin/activate
pip install requests rich
python my_script.py

You write:

uv run my_script.py

Or with inline dependencies declared in the script itself.

Running ADW Scripts

# All ADW scripts use uv run
uv run adws/adw_plan_build.py 42
uv run adws/adw_sdlc.py 42 --skip-e2e
uv run adws/adw_triggers/trigger_cron.py

uv reads the pyproject.toml in the adws/ directory for dependencies.

Inline Script Dependencies (PEP 723)

For standalone scripts outside the adws/ project, declare dependencies inline:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://api.example.com/data")
pprint(resp.json())

Run it:

uv run my_script.py

uv creates an isolated environment with exactly those dependencies, runs the script, and cleans up. No venv, no pip, no activation.

Adding Dependencies to an Existing Script

# uv add --script automatically updates the inline metadata
uv add --script my_script.py 'httpx' 'pydantic>=2'

Specifying Python Version

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///

uv will download the required Python version if it's not installed.

Running with a Specific Python Version

uv run --python 3.11 my_script.py
uv run --python 3.12 my_script.py

Running with Extra Dependencies (Without Modifying Script)

uv run --with rich my_script.py
uv run --with 'rich>12,<13' --with requests my_script.py

Locking Dependencies

For reproducible script execution:

uv lock --script my_script.py
# Creates my_script.py.lock

# Subsequent runs use the locked versions
uv run my_script.py

Using in Projects (pyproject.toml)

The ADW system uses adws/pyproject.toml to declare dependencies:

[project]
name = "adws"
requires-python = ">=3.12"
dependencies = [
    "anthropic",
    "PyGithub",
    "gitpython",
    "pydantic",
    "python-dotenv",
]

Run any script in the project context:

cd adws
uv run adw_plan_build.py 42  # uv installs from pyproject.toml automatically

Skip project installation for scripts that don't need it:

uv run --no-project standalone_script.py

Shebang for Executable Scripts

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

import httpx
print(httpx.get("https://example.com").status_code)

chmod +x my_script.py
./my_script.py  # No "uv run" needed

Common Patterns in ADW Scripts

ADW scripts use uv run with:

• --no-project when running utility scripts outside the adws/ directory
• Inline metadata for one-off research or setup scripts
• The adws/ pyproject.toml for all pipeline scripts

To run a quick research script alongside your ADW project:

# /// script
# requires-python = ">=3.11"
# dependencies = ["anthropic", "python-dotenv"]
# ///

import os
from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize the key ADW concepts"}]
)
print(message.content[0].text)

uv run my_research.py