single-file-uv-scripter

Creates self-contained Python scripts with inline PEP 723 metadata for UV. Embeds dependencies directly in script headers for zero-config execution via `uv run`. Triggers on keywords: uv script, single file script, inline dependencies, PEP 723, self-contained python, uv run script, standalone script

⭐16stars🔀1forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill automates the creation of self-contained Python scripts by embedding PEP 723 inline metadata for the uv package manager. It solves the overhead of manual environment management and dependency configuration for standalone scripts, enabling zero-config execution and high portability. By streamlining the 'uv run' workflow, it allows developers to move from idea to executable script instantly without the need for complex project structures or pyproject.toml files.

Use Cases

  • Rapid CLI Prototyping: Quickly generate standalone command-line tools using libraries like Typer or Rich for internal tasks without setting up a full project directory.
  • Portable Data Processing: Create single-file scripts for data analysis using Polars or Pandas that can be easily shared and executed on any machine with uv installed.
  • DevOps and Automation: Build self-contained maintenance or infrastructure scripts that manage their own dependencies, ensuring consistent behavior across different environments.
  • API Testing and Integration: Draft isolated scripts to interact with web services using httpx or requests, perfect for testing endpoints or performing one-off data migrations.
namesingle-file-uv-scripter
descriptionCreates self-contained Python scripts with inline PEP 723 metadata for UV. Embeds dependencies directly in script headers for zero-config execution via `uv run`. Triggers on keywords: uv script, single file script, inline dependencies, PEP 723, self-contained python, uv run script, standalone script
project-agnostictrue

Single-File UV Scripter

Creates self-contained Python scripts with inline dependency declarations per PEP 723. Scripts execute via uv run script.py with automatic dependency resolution.

Inline Metadata Format

# /// script
# dependencies = [
#   "package-name",
#   "package>=1.0,<2.0",
# ]
# requires-python = ">=3.12"
# ///

Syntax Rules

Element Format Required
Open marker # /// script Yes
Close marker # /// Yes
Dependencies TOML array, each line # prefixed Yes (can be empty [])
Python version requires-python = ">=3.X" Recommended

UV-Specific Extensions

# /// script
# dependencies = ["requests"]
# requires-python = ">=3.12"
# [tool.uv]
# exclude-newer = "2024-01-15T00:00:00Z"
# ///
  • exclude-newer: RFC 3339 timestamp for reproducible builds (pins to releases before date)
  • index: Alternative PyPI index URL

Template

#!/usr/bin/env -S uv run
# /// script
# dependencies = [
#   "DEPENDENCY",
# ]
# requires-python = ">=3.12"
# ///
"""One-line description of script purpose."""
from __future__ import annotations

# imports here

def main() -> None:
    """Entry point."""
    pass

if __name__ == "__main__":
    main()

Commands

Action Command
Initialize uv init --script name.py --python 3.12
Add dep uv add --script name.py 'pkg>=1.0'
Run uv run name.py [args]
Make executable chmod +x name.py then ./name.py

Shebang Options

#!/usr/bin/env -S uv run                    # Standard
#!/usr/bin/env -S uv run --quiet            # Suppress UV output
#!/usr/bin/env -S uv run --python 3.12      # Pin Python version

Common Patterns

CLI with Arguments

#!/usr/bin/env -S uv run
# /// script
# dependencies = ["typer>=0.9", "rich"]
# requires-python = ">=3.12"
# ///
import typer
app = typer.Typer()

@app.command()
def main(name: str) -> None:
    print(f"Hello {name}")

if __name__ == "__main__":
    app()

HTTP Client

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

def main() -> None:
    r = httpx.get("https://api.example.com/data")
    print(r.json())

if __name__ == "__main__":
    main()

Data Processing

#!/usr/bin/env -S uv run
# /// script
# dependencies = ["polars>=1.0", "rich"]
# requires-python = ">=3.12"
# ///
import polars as pl
from rich import print

def main() -> None:
    df = pl.read_csv("data.csv")
    print(df.describe())

if __name__ == "__main__":
    main()

Constraints

  • Metadata block MUST appear before any Python code (after shebang/encoding is OK)
  • Project dependencies are IGNORED when running inline-metadata scripts
  • Each script is isolated: deps resolved fresh per script
  • Empty deps array required if no dependencies: dependencies = []

Workflow

  1. Create: Write script with inline metadata block
  2. Test: uv run script.py (UV auto-installs deps)
  3. Iterate: uv add --script script.py 'new-pkg' to add deps
  4. Deploy: Script is self-contained, copy anywhere with UV installed