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!

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

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

This inserts a metadata block at the top of the file. 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

uv reads the dependencies list, installs requests into an isolated environment, and runs the script. The output is a random piece of GitHub’s design philosophy.

Next steps

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

Please submit corrections and feedback...