Skip to content

Run your first Python script with uv

by Tim Hopper
uv

uv can run Python scripts without any prior Python installation. This tutorial starts with a one-line script and builds up to using a third-party package through inline script metadata.

Prerequisites

Install uv on your system.

Tip

Python does not need to be installed beforehand. uv downloads and manages Python interpreters automatically.

Create and run a script

Create a project directory 

mkdir hello-uv
cd hello-uv

Write the script

Create a file called hello.py with the following content:

hello.py
print("Hello, World!")

Run it 

$ uv run hello.py
Hello, World!

If you see command not found: uv instead, your shell cannot find the binary. Close and reopen your terminal so it picks up the install, or revisit the uv install instructions to confirm it is on your PATH.

uv finds (or installs) a Python interpreter, then executes the script. No virtual environment setup, no activation step.

Note

The first run on a clean machine is slower because uv downloads the Python interpreter. Subsequent runs reuse the cached interpreter and start almost instantly. Notice that you never had to create or activate a virtual environment; uv handled that for you.

Add a third-party dependency

Most real scripts need packages beyond the standard library. uv supports PEP 723 inline script metadata, which lets a script declare its own dependencies.

Add the requests dependency to the script:

$ uv add --script hello.py requests
Updated `hello.py`

Open hello.py and notice that uv prepended a # /// script block above your print line. That block is the PEP 723 metadata uv reads to know which packages to install before running the script. The exact field order and requires-python value depend on your uv version and the Python interpreter uv chose; what matters is the surrounding # /// script and # /// markers.

Now replace the script contents with:

hello.py
# /// script
# dependencies = ["requests"]
# requires-python = ">=3.10"
# ///

import requests

response = requests.get("https://api.github.com/zen")
print(response.text)

Run it again:

$ uv run hello.py
Installed 5 packages in 95ms
Responsive is better than fast.

uv reads the dependencies list, installs requests (and its four transitive dependencies) into an isolated environment, then runs the script. The exact quote you see will vary; https://api.github.com/zen rotates through GitHub’s design philosophy. Run the script a second time and notice that the Installed 5 packages line disappears: uv reuses the cached environment instead of resolving and downloading again.

If you see error: failed to parse: ... after editing the metadata block, double-check that every line between # /// script and # /// starts with # and that both marker lines are present. PEP 723 is strict about the markers.

Next steps

Last updated on
Publishing Your First Python Package to PyPISet up a data science project with uv