TIL: Inline dependencies in Python scripts

When sharing a Python script as a gist, you’d typically include a requirements.txt or a pyproject.toml with uv.lock. Multiple files for one script.

Turns out there’s a cleaner way. PEP 723 lets you embed dependencies and Python version requirements directly in the script:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com/zen")
print(f"[bold green]{response.text}[/bold green]")

Run it with uv:

uv run script.py

uv reads the inline metadata, installs the right Python version if needed, creates an isolated environment, installs dependencies, and runs the script. One file, fully self-contained!

The format

The block uses TOML inside comments:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "pandas",
#   "matplotlib>=3.8",
# ]
# ///

You can also embed tool-specific config (same [tool] table semantics as pyproject.toml):

# /// script
# dependencies = ["requests"]
# [tool.uv]
# exclude-newer = "2025-01-01"
# ///

Agent skills

This is particularly useful for Claude Code or other agent skills. A skill is just a script that the agent can invoke - having dependencies declared inline means the script is truly portable. No setup instructions, no pyproject.toml, no “first install X”, just one file that works.