Skip to content

Use PEP 723 inline script metadata for zero-install tooling scripts

This is a principle

A reusable technical claim: something I would want true in any of my work.

Claim. For small standalone tooling scripts, declare their dependencies in an inline PEP 723 metadata block and run them with a launcher that provisions those deps on the fly - so the script needs no project install or virtualenv.

When to apply. Small, self-contained utility/guard scripts (CI checks, one-off tools). Not for application code that belongs to a project's own dependency set.

Why. A guard script that imports packaging shouldn't force every consumer to first install a project environment, nor should it silently depend on whatever happens to be on the system Python. Inline metadata makes the script's dependencies explicit and self-contained: the launcher reads the header, builds an ephemeral environment, and runs it - reproducibly, with zero prior setup.

Snippet.

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["packaging"]
# ///
"""Ensure .python-version is consistent with requires-python."""

How enforced. Convention: standalone scripts carry a # /// script block and are invoked via uv run --script (or equivalent). Pairs well with keeping such guards runnable from pre-commit without a project sync.

The following pages link to this page: