uv-anywhere

Write hyper-portable Python scripts that install their own dependencies using uv.
The target system only needs any version of Python 2 or 3, curl, and sh.

Usage

The most portable way of using this script is by pasting two lines of code at the top of any Python file after declaring dependencies using PEP 723 syntax.

For example, if I write main.py with

# /// script
# requires-python = "==3.10.19"
# dependencies = ["requests==2.32.4"]
# ///
exec(__import__('urllib.request',fromlist=['']).urlopen('https://raw.githubusercontent.com/nathom/uv-anywhere/main/uv_anywhere.py').read().decode())
ensure_uv()

import sys, requests
print("Python version:", sys.version)
print("Requests version:", requests.__version__)

Running python main.py with any Python version should output

Python version: 3.10.19 (main, Jan 13 2026, 17:48:23) [Clang 21.1.4 ]
Requests version: 2.32.4

If your target system may only have Python 2, use this instead:

exec((lambda:__import__('urllib.request'if __import__('sys').version_info[0]>=3else'urllib2',fromlist=['']).urlopen('https://raw.githubusercontent.com/nathom/uv-anywhere/main/uv_anywhere.py').read().decode())())
ensure_uv()

You can also ship your script along with uv_anywhere.py and import it in the standard way:

from uv_anywhere import ensure_uv
ensure_uv()

This is preferred if you want to avoid the admittedly suspicious looking exec call, or the overhead of downloading the script from GitHub on every run.

How it works

1. exec() fetches and runs uv_anywhere.py from this repo
2. ensure_uv() installs uv if missing, then re-execs script under uv run
3. uv resolves dependencies, script runs with deps available

Use Cases

• Easily deploying scripts to a fleet of heterogeneous hardware
• Hot-swapping systemd service scripts without extra setup
• Running scripts on machines without root access
• Sharing single-file utilities with colleagues
• Portable CLI tools that "just work"
• Raspberry Pi and embedded devices with arbitrary system Python versions

Guarantees

For any script run with uv-anywhere, the stdout and stderr is guaranteed to exactly match the output had the script been run in a correct, externally resolved environment -- UNLESS uv fails to resolve dependencies in which case the error will be dumped to stderr.

Importing a script using uv-anywhere as a library will not work! Only the entry point should use uv-anywhere!

Supported Platforms

uv-anywhere works on Linux, macOS, and Windows. All 3 are continuously tested in CI.