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
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.
| name | single-file-uv-scripter |
|---|---|
| description | 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 |
| project-agnostic | true |
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
- Create: Write script with inline metadata block
- Test:
uv run script.py(UV auto-installs deps) - Iterate:
uv add --script script.py 'new-pkg'to add deps - Deploy: Script is self-contained, copy anywhere with UV installed