Managing Python Scripts with uv Inline Metadata

Description

Managing Python script dependencies and version requirements has traditionally been challenging. The uv tool, combined with Python’s new inline script metadata standard, offers a modern solution to this problem.

Python recently added a standard format for inline script metadata. It allows for selecting Python versions and defining dependencies in a section at the top of the script declaring the dependencies using TOML.

What is Inline Script Metadata?

Python’s inline script metadata format provides a standardized way to specify Python versions and dependencies directly within your scripts. When combined with uv, this creates a powerful workflow for managing script environments.

Key Features

• Declare dependencies inline using TOML format
• Specify Python version requirements
• Automatic environment creation
• Isolated from project dependencies

Prerequisites

• uv installed ( check out this article for more information)
• Basic familiarity with Python packaging

Usage^[1]

Use uv init --script to initialize scripts with the inline metadata.

1

uv init --script example.py --python 3.12

Declaring script dependencies

The inline metadata format allows the dependencies for a script to be declared in the script itself.

uv supports adding and updating inline script metadata for you.

Use uv add --script to declare the dependencies for the script.

1

uv add --script example.py 'requests<3' 'rich'

This will add a script section at the top of the script declaring the dependencies using TOML:

example.py

1
2
3
4
5
6
7
8
9
10
11
12
13

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

uv will automatically create an environment with the dependencies necessary to run the script.

Running the script

1

uv run example.py

When using inline script metadata, even if uv run is used in a project, the project’s dependencies will be ignored.

uv also respects Python version requirements:

example.py

1
2
3
4
5
6
7
8

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///

# Use some syntax added in Python 3.12
type Point = tuple[float, float]
print(Point)

The dependencies field must be provided even if empty.

• uv run will search for and use the required Python version.
• The Python version will download if it is not installed.

Additional Resources

• uv Documentation
• PEP 723 - Inline Script Metadata