How to run python scripts in 0 steps

uv is an “extremely fast Python package and project manager, written in Rust”.

It took off last year as an alternative for previous python package managers such as pip, pip-tools, poetry, and virtualenv.

The coolest thing about UV, apart from the fact that it’s really fast and makes managing python virtually a solved problem, is that you can use it as a way to run python scripts in 0 steps!

If you had a python script, you’d need at least one pre-flight step before you could run it on a new machine:

install all dependencies
- (can include python itself, or libraries, or maybe even your preferred package manager itself)
run the script

uv, however, when combined with inline script metadata (PEP 723) and uv Scripts , can turn any single-file script into a fully portable executable (kind of like pex but not really).

With a clever polyglot trick—a single file written to be valid in multiple languages (in this case, shell and Python)—we can also make uv self-install, so we don’t even need to have it beforehand!

Embed python and library versions on the script itself

Inline script metadata can be used to embed any and all dependencies for a script in the script itself:

1
# /// script
2
# requires-python = "~=3.12"
3
# dependencies = [
4
# "marimo==0.11.25",
5
# "numpy",
6
# "requests",
7
# ]
8
# ///

If you include the commented snippet above anywhere in your code, PEP 723 tells us that it will be identified and parsed to identify python version 3.12 and these marimo, numpy and requests dependencies.

uv can now resolve any dependency and execute your script:

1
uv run --script my_script.py

Turning the script into an executable file

We can also use a shebang added at the top of the file to make it easier.

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

now, we can just do either way to execute it:

1
./my_script.py  # if you did `chmod +x my_script.py`
2
sh my_script.py # if you didn't

the problem is: we’re still depending on having uv pre-installed!

install uv, python and dependencies in zero steps and run the script with a polyglot trick

uv itself is also really easy to install:

1
curl -LsSf https://astral.sh/uv/install.sh | sh

1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Beyond the python and library versions, we can also embed the uv installation on the script itself:

1
#!/usr/bin/env sh
2

3
""":"
4
# Polyglot trick: Python sees a triple-quoted string, bash sees "" then ":" (no-op)
5
# Install UV if needed (zero-dependency setup) - redirect output to stderr to preserve clean stdout
6
which uv >/dev/null || {
7
    echo ">>> uv install required" >&2 \
8
    && curl -LsSf https://astral.sh/uv/install.sh | sh >&2 \
9
    && echo ">>> uv install done\n\n" >&2
10
}
11

12
# Execute with UV, replacing shell process (preserves stdio)
13
exec uv run --script --quiet "$0" "$@"
14
":"""

Key differences here:

we turned the shebang back into bash
we included a command on the file itself to check for uv and install if missing
then a command to use uv to run the file with the chosen versions for python and libs

The same file is doing three things at once:

installing uv if needed
invoking uv
hosting python code

putting it all together

1
#!/usr/bin/env sh
2

3
""":"
4
# Polyglot trick: Python sees a triple-quoted string, bash sees "" then ":" (no-op)
5
# Install UV if needed (zero-dependency setup) - redirect output to stderr to preserve clean stdout
6
which uv >/dev/null || {
7
    echo ">>> uv install required" >&2 \
8
    && curl -LsSf https://astral.sh/uv/install.sh | sh >&2 \
9
    && echo ">>> uv install done\n\n" >&2
10
}
11

12
# Execute with UV, replacing shell process (preserves stdio)
13
exec uv run --script --quiet "$0" "$@"
14
":"""
15

16
# /// script
17
# requires-python = "~=3.12"
18
# dependencies = [
19
#     "marimo==0.11.25",
20
#     "numpy",
21
#     "requests",
22
# ]
23
# ///
24

25
import marimo
26
import numpy as np
27
import requests
28

29
print(f"using marimo.{marimo.__version__}")
30
print(f"using numpy.{np.__version__}")
31
print(f"using requests: {requests.__file__}")
32

33
# Example: Fetch authenticated data
34
session = requests.Session()
35
session.cookies = requests.cookies.RequestsCookieJar()
36
# Add your authentication logic here
37
print("Script running worry-free with dependencies resolved!")

if you run sh my_script.py on ANY brand new machine, you should see:

1
$ sh my_script.py
2
using marimo.0.11.25
3
using numpy.2.3.0
4
using requests: /Users/diegolm/.cache/uv/environments-v2/py-2d879b88d0cc5794/lib/python3.12/site-packages/requests/__init__.py
5
Script running worry-free with dependencies resolved!

REGARDLESS of any pre-conditions.

credits

I first found this tip on Paul Willot’s blog: Standalone python script with uv

I then modified it so it were stdio-MCP-friendly (mostly, redirect stuff to sterr and preserve clean stdio)

(blog post WIP)