How to write self-contained Python scripts using PEP 723 inline metadata

Prerequisites

• uv installed on your system
• Basic knowledge of Python scripting

Step 1: Create a simple script

First, create a basic Python script that requires external dependencies:

# github_stats.py
import requests

def get_repo_stats(repo):
    url = f"https://api.github.com/repos/{repo}"
    response = requests.get(url)
    data = response.json()
    return data

if __name__ == "__main__":
    repo = "astral-sh/uv"
    stats = get_repo_stats(repo)
    print(f"Repository: {stats['full_name']}")
    print(f"Stars: {stats['stargazers_count']}")
    print(f"Forks: {stats['forks_count']}")
    print(f"Open Issues: {stats['open_issues_count']}")

Step 2: Add dependencies using uv

Instead of manually editing the script to add metadata, use uv’s built-in command:

uv add --script github_stats.py --python="3.9" requests

This adds the required inline metadata to your script:

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

import requests
# rest of script...

Step 3: Run the script with uv

Now run your script using uv:

uv run github_stats.py

When you run this command, uv will:

1. Read the inline metadata
2. Create a temporary virtual environment
3. Install the specified dependencies
4. Execute your script in this environment

Step 4: Make your script executable (Unix systems)

To run your script directly without typing uv run, add a shebang line and make it executable:

# Edit your script to add this as the first line
#!/usr/bin/env -S uv run --script

# Then make it executable
chmod +x github_stats.py

Now you can run the script directly:

./github_stats.py

Running with pdm

Inline metadata is a Python standard defined in PEP 723, and can also be used with other tools like PDM (pdm run github_stats.py), Hatch (hatch run github_stats.py), and pip (pipx run github_stats.py)