runnable independent python scripts with uv + pep
uv script shebang
Start your script with:
#! /usr/bin/env -S uv run --script
uv install --script
Then declare script dependencies with this:
script_filename=
script_packages=
uv add --script "$script_filename" "$script_packages"
example
uv add --script standalone-script aiohttp rich
adds package dependies inside the file standalone-script
like this:
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "aiohttp",
# "rich"
# ]
# ///
Inline script metadata was added in PEP 723 – Inline script metadata
Full example script on github
gitllm is a script I threw together to grab relevant SvelteKit files from a github repo and dump them into a markdown file for feeding to LLM’s like copilot’s custom prompts.
bonus reading
What’s the -S
in the shebang? (split-string)
man env
shows that -S
:
Split apart the given string into multiple strings, and process each of the resulting strings as separate arguments to the env utility.
Without -S
, the env command tries to find a program literally named “uv run —script” rather than running uv
with the arguments ”run
” and ”--script
“.
>> import subprocess
>> subprocess.run(['echo', 'yo'])
yo
>> subprocess.run('echo yo')
# ... (extra debugging details)
FileNotFoundError: [Errno 2] No such file or directory: 'echo yo'