Dependencies

Every supypowers script declares its own dependencies. There is no shared requirements.txt or virtual environment -- each script runs in complete isolation with exactly the packages it needs.

The Script Metadata Block

Dependencies are declared using the PEP 723 inline script metadata format:

# /// script
# dependencies = [
#   "pydantic",
#   "httpx",
# ]
# ///

This block must appear at the top of the file, before any imports. The # /// script and # /// markers are required.

How Dependency Resolution Works

When supypowers runs a script, the following happens:

1. The # /// script block is parsed to extract the dependency list
2. uv run --with pydantic --with httpx ... python -c [runner_code] is executed
3. uv resolves and installs the dependencies into a cached environment
4. The script runs in that environment
5. Subsequent runs reuse the cached environment (near-instant startup)

supypowers run myscript:func '{}'
     │
     ├─→ Parse # /// script block → ["pydantic", "httpx"]
     ├─→ uv run --with pydantic --with httpx python -c <code>
     │        │
     │        ├─→ Resolve + install deps (cached after first run)
     │        └─→ Execute function in isolated environment
     └─→ Return JSON result

Pydantic is Always Required

Every script needs at least pydantic because the supypower contract requires BaseModel for input types:

# /// script
# dependencies = ["pydantic"]
# ///

Version Pinning

You can pin specific versions using standard pip syntax:

# /// script
# dependencies = [
#   "pydantic>=2.0",
#   "httpx>=0.25,<1.0",
#   "beautifulsoup4==4.12.3",
#   "openai~=1.0",
# ]
# ///

Complex Dependency Examples

HTTP API Client

# /// script
# dependencies = [
#   "pydantic",
#   "httpx",
# ]
# ///

Web Scraping

# /// script
# dependencies = [
#   "pydantic",
#   "httpx",
#   "beautifulsoup4",
#   "markdownify",
# ]
# ///

Database Access

# /// script
# dependencies = [
#   "pydantic",
#   "sqlalchemy>=2.0",
#   "psycopg2-binary",
# ]
# ///

Data Science / ML

# /// script
# dependencies = [
#   "pydantic",
#   "pandas>=2.0",
#   "numpy",
#   "scikit-learn",
# ]
# ///

Browser Automation

# /// script
# dependencies = [
#   "pydantic",
#   "playwright",
#   "beautifulsoup4",
#   "markdownify",
# ]
# ///

Image Processing

# /// script
# dependencies = [
#   "pydantic",
#   "Pillow>=10.0",
# ]
# ///

Why Per-Script Isolation?

Traditional approaches share a virtual environment across all tools. This causes problems:

Caching

uv caches resolved environments aggressively. The first run of a script may take a few seconds to install dependencies, but subsequent runs reuse the cached environment and start near-instantly.

The cache is stored in uv's global cache directory (typically ~/.cache/uv/ on Linux/macOS). You can clear it with:

uv cache clean

Secrets and Environment Variables

Scripts can access secrets passed via --secrets:

# Inline secret
supypowers run my_tool:func '{}' --secrets API_KEY=sk-abc123

# From a .env file
supypowers run my_tool:func '{}' --secrets .env

# Multiple secrets
supypowers run my_tool:func '{}' --secrets API_KEY=sk-abc --secrets .env

Access them in code with os.environ.get():

import os

api_key = os.environ.get("API_KEY")

Troubleshooting

What's Next

• Creating Tools -- The supypower contract and function structure
• Testing -- Verify your tools work before handing them to agents
• Publishing -- Share tools across projects