Single-file executable Python scripts with uv

This note is based on a lightning talk Tero did in archipylago meetup in March, 2025. His example code is at https://codeberg.org/tero/simple-uv-script-demo

With uv, it’s possible to write and run Python scripts that are self-contained, including dependencies and Python version requirements that can be run without setting up virtual environments.

The first step is to add PEP 723 script metadata:

# /// script
# requires-python = ">=3.10"
# dependencies = [
#    "bs4",
# ]
# ///

This will set the required Python version to be at least 3.10 (and if you don’t have a matching Python version installed, uv will handle that for you as well!) and to include BeautifulSoup as a dependency.

Then, to make it runnable without invoking uv manually, add a shebang at the start of the file:

#!/usr/bin/env -S uv run --quiet --script

With a script like this, the only thing the user needs is uv. Everything else (Python and dependencies) are handled by it and it will guarantee that even if the user only has an older, incompatible version, the script will run with a correct one.