python-scripts

name	python-scripts
description	Use when writing standalone Python scripts (one-off scripts, utilities, not part of a larger Python project with pyproject.toml or setup.py). Provides UV shebang template and best practices.

Standalone Python Scripts

UV Shebang Template

For standalone Python scripts, always use the UV shebang format:

#!/usr/bin/env -S uv run --script
#
# /// script
# dependencies = [
#   "requests",
#   "click",
# ]
# [tool.uv]
# exclude-newer = "2025-08-23T00:00:00Z"
# ///

import requests
import click

# Your script code here

Key Points

• Self-contained: All dependencies declared in the file
• No virtual env needed: UV handles dependencies automatically
• Execution: Run directly with uv run script.py or ./script.py (if executable)
• Date pinning: The exclude-newer ensures reproducible builds
• PEP 723 compliant: Uses the inline script metadata standard

When to Use

✅ Use this for:

• One-off automation scripts
• CLI utilities
• Data processing scripts
• Quick prototypes
• Scripts without a containing project

❌ Don't use this for:

• Files in a project with pyproject.toml or setup.py
• Modules meant to be imported
• Production services/applications

Example Script

#!/usr/bin/env -S uv run --script
#
# /// script
# dependencies = [
#   "httpx",
#   "rich",
# ]
# [tool.uv]
# exclude-newer = "2025-08-23T00:00:00Z"
# ///

import httpx
from rich import print

def main():
    response = httpx.get("https://api.github.com")
    print(f"Status: {response.status_code}")

if __name__ == "__main__":
    main()

Making Scripts Executable

chmod +x script.py
./script.py  # Run directly