uv, pipx and inline script metadata in Python

A project with three packages needs four steps on every computer it runs on: make an environment, install the right versions into it, record those versions, and repeat all of it after each change. The venv and pip of the previous lesson do each step, and the steps go stale the day someone forgets one. Two tools do this bookkeeping for you: uv manages a whole project, and pipx installs command-line applications, each in an environment of its own.

Below you set up a project with uv and see what it checks before every run, compare a range of versions with a lock file, give a single script its own list of dependencies, and install tools so that they never clash with your projects. Neither tool is part of Python: both are open-source programs that you install once.

uv keeps a project’s environment in step with pyproject.toml

uv, made by Astral and licensed under MIT or Apache-2.0, is one program that does the jobs of several: it installs Python versions (uv python install 3.14), creates virtual environments, works out which versions of your dependencies fit together, records them, and runs your code. Install it with a package manager (brew install uv on macOS, winget install --id=astral-sh.uv -e on Windows), with pipx install uv, or with the installer script from uv’s documentation. A script you download and run has the same access to your computer as you, so look at it first; the documentation shows how.

Three commands start a project:

1. uv init weather-notes creates the folder weather-notes with a pyproject.toml, a .python-version file that names the Python version to use, a README.md, a .gitignore, a Git repository and starter code in src/weather_notes/__init__.py.
2. uv add rich, in that folder, writes the requirement rich>=15.0.0, the newest version that fits as the lowest allowed, into pyproject.toml. It also creates .venv if there is none, installs rich into it and records the exact versions in uv.lock.
3. uv run weather-notes runs the command that uv init set up, and uv run some_file.py runs any file, inside the project’s environment.

What makes uv run dependable is what it checks before it runs anything. Step through one run:

So you never activate anything and never run with a stale set of packages. uv remove rich takes a dependency out again, uv sync makes .venv match uv.lock exactly (after you pull a teammate’s changes, for example), and uv lock --upgrade-package rich moves one package to its newest allowed version.

pyproject.toml is not a uv invention: it is the standard file in which a Python project describes itself, written in TOMLTom's Obvious, Minimal Language, a text format for settings: key = value lines grouped under headings in square brackets., and any tool can read it. The standard library reads it with tomllib:

[project]
name = "weather-notes"
version = "0.1.0"
description = "Short notes about the weather"
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "rich>=15.0.0",
]

[project.scripts]
weather-notes = "weather_notes:main"

[build-system]
requires = ["uv_build>=0.13.1,<0.14"]
build-backend = "uv_build"

import tomllib

# tomllib, in the standard library since Python 3.11, reads TOML; it needs the file opened in binary mode.
with open("pyproject.toml", "rb") as file:
    pyproject = tomllib.load(file)

project = pyproject["project"]
print("Project:", project["name"], project["version"])
print("Needs Python", project["requires-python"])
for requirement in project["dependencies"]:
    print("Depends on", requirement)
for command, target in project["scripts"].items():
    print("Adds the command", command, "which runs", target)
print("Built by", pyproject["build-system"]["build-backend"])

Project: weather-notes 0.1.0
Needs Python >=3.14
Depends on rich>=15.0.0
Adds the command weather-notes which runs weather_notes:main
Built by uv_build

The [project] table holds the name, the version, the Python versions the project supports and its dependencies; [project.scripts] adds the weather-notes command, and [build-system] names uv_build, the backend that turns the project into a package. Since uv 0.12, uv init gives an application a build system by default.

A lock file turns ranges into one exact set of versions

A requirement such as rich>=15.0.0 is a version specifierversion specifier: The part of a requirement that says which releases are acceptable, such as >=1.2,<2 or ~=1.2. Releases are compared number by number, and pip installs the newest one that meets every condition. More in “Finding and installing third-party packages”, a range: any version from 15.0.0 on is acceptable. Which version you actually get is decided when the environment is built, and it can change from one week to the next. This program follows a made-up package, tablekit, through its releases in weeks 1, 5 and 9, and compares a fresh install from the range with an install from the lock:

# tablekit is a made-up package: the versions its index offers in three weeks.
releases = {
    1: ["2.3.0"],
    5: ["2.3.0", "2.4.0"],
    9: ["2.3.0", "2.4.0", "3.0.0"],
}
locked = "2.3.0"  # what uv.lock recorded in week 1


def as_numbers(version):
    return tuple(int(part) for part in version.split("."))


def newest_allowed(available, minimum):
    allowed = [v for v in available if as_numbers(v) >= as_numbers(minimum)]
    return max(allowed, key=as_numbers)


print("Week  tablekit>=2.3.0 gives  uv.lock gives")
for week, available in releases.items():
    print(f"{week:>4}  {newest_allowed(available, '2.3.0'):<21}  {locked}")

Week  tablekit>=2.3.0 gives  uv.lock gives
   1  2.3.0                  2.3.0
   5  2.4.0                  2.3.0
   9  3.0.0                  2.3.0

In week 9 a fresh install from the range gets 3.0.0, a new major version that may rename what your code calls, while everyone who installs from the lock still gets 2.3.0. A lock filelock file: A file that records every package an application installs, direct and indirect, with its exact version, where each file came from and the file's hash, so the next install gets the same files. pylock.toml is the standard format. records the exact version of every package that was installed, including the dependencies of your dependencies: rich 15.0.0 itself needs markdown-it-py and Pygments, so uv.lock lists them too, each with its exact version. Press Edit, add "3.1.0" to week 9’s list and run it again: the range moves on, the lock does not.

uv keeps its lock in uv.lock, which belongs in version control and is never edited by hand (the .venv folder, again, is not committed). A standard format for lock files, pylock.toml, is defined by PEP 751: uv export --format pylock.toml writes one, and pip 26.2.1 has an experimental pip lock command that writes one too. The requirements.txt that pip freeze writes is the older and simpler way to pin versions, and still the most widely supported one.

A script can carry its own dependency list

Not everything is a project. A single file that you run now and then can say what it needs in a comment block at its top, called inline script metadatainline script metadata: A comment block in a Python script, opened by # /// script and closed by # ///, whose lines hold TOML such as requires-python and dependencies. Script runners read it; Python itself ignores it., a packaging standard since PEP 723:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "rich",
# ]
# ///
from rich import print

print("[bold green]Report ready[/bold green]")

Traceback (most recent call last):
  File "report.py", line 7, in <module>
    from rich import print
ModuleNotFoundError: No module named 'rich'

Python itself ignores the block: to python3 it is only comments. That is why the run above, with plain CPython 3.14.8, stops at the import with ModuleNotFoundError. A tool that reads the block does better: uv run report.py and pipx run report.py read it, build an environment that contains rich, and run the script there. pipx keeps that environment and builds a fresh one when the list of dependencies changes.

The rules are short. The block starts with a line that is exactly # /// script and ends with a line that is exactly # ///. Every line between them is a comment: take away the # and the space after it, and what is left is TOML, with the keys requires-python (the Python versions the script runs on) and dependencies (a list of requirements, like the one in pyproject.toml). A script may have only one script block; tools refuse a file with two. Step through a program that reads the block of report.py the way such a tool does:

import tomllib
from pathlib import Path

src = Path("report.py").read_text()
inside = False
toml = []
for line in src.splitlines():
    if line == "# /// script":
        inside = True
    elif line == "# ///":
        inside = False
    elif inside:
        toml.append(line[2:])

meta = tomllib.loads("\n".join(toml))
print("requires-python:", meta["requires-python"])
print("dependencies:", meta["dependencies"])

requires-python: >=3.14
dependencies: ['rich']

The loop kept the four lines between the two markers, each without its first two characters, and tomllib turned them into the string >=3.14 and the list ['rich'].

uv can also write the block for you: uv init --script report.py creates a new script with one, and uv add --script report.py rich adds a dependency to it. uv expects a dependencies key even when the list is empty, and a script is locked only when you ask, with uv lock --script report.py, which writes report.py.lock.

pipx and uv tool give each application its own environment

Some packages are applications that you run as commands, such as the linter Ruff, rather than libraries that your code imports. Install those with pipxpipx: A tool that installs each Python application into a virtual environment of its own and links only its commands into a folder on PATH, ~/.local/bin by default. uv tool does the same job. or with uv tool: each application gets a virtual environment of its own, so its dependencies never clash with your projects or with each other, and only its commands are put on your PATH. Step through one install:

pipx itself comes from a package manager (brew install pipx on macOS, sudo apt install pipx on Ubuntu, scoop install pipx on Windows) or, on Windows, from py -m pip install --user pipx. uvx is short for uv tool run. A tool installed this way is not importable by your own code: it lives in its own environment, which is the point. A tool that has to import your project, such as pytest running your tests, belongs in the project instead, as a development dependency (uv add --dev pytest), and runs with uv run pytest.

Choose the tool by the job

All three do the same steps underneath: a virtual environment, an install, a record of versions. They differ in how much of it they do for you and in what they are for:

Read the table from the job you have. On a school computer where you may install nothing but Python, venv and pip are what you have, and they are enough. A team project with dependencies and a test run on every change is uv’s job, with uv.lock committed. A linter you use in every folder goes to pipx or uv tool, and a script you run once a month carries its own block and runs with uv run.

None of these replaces knowing venv and pip: uv and pipx automate the same steps, and when one of them does something unexpected, the previous lesson’s commands are how you look inside.

Practise: read a script’s metadata

Write the part of a script runner that reads the block: return its TOML as a dict, None when there is no block, and raise ValueError for a script with two. The sample tests run in your browser:

import tomllib


def parse_script_metadata(text):
    """Return the TOML of the script's '# /// script' block as a dict, or None if it has none."""
    return None

from script_meta import parse_script_metadata

BLOCK = """# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "rich",
# ]
# ///
print("Report ready")
"""


def test_one_block():
    """reads the TOML of the block"""
    assert parse_script_metadata(BLOCK) == {"requires-python": ">=3.14", "dependencies": ["rich"]}


def test_no_block():
    """gives None for a script without a block"""
    assert parse_script_metadata('print("Report ready")\n') is None


def test_two_blocks():
    """refuses a script with two script blocks"""
    try:
        parse_script_metadata(BLOCK + BLOCK)
    except ValueError:
        return
    raise AssertionError("a script with two script blocks must raise ValueError")


def test_empty_dependencies():
    """reads a block whose dependencies list is empty"""
    assert parse_script_metadata("# /// script\n# dependencies = []\n# ///\n") == {"dependencies": []}


def test_line_of_only_a_hash():
    """treats a line that is only # as an empty line of the block"""
    text = '# /// script\n# requires-python = ">=3.14"\n#\n# dependencies = []\n# ///\n'
    assert parse_script_metadata(text) == {"requires-python": ">=3.14", "dependencies": []}

Finish with the questions below, which follow your answers: a miss brings a simpler question on the same idea, and each choice carries its own explanation:

Interview questions

Warm-up (fresher): what is the difference between pyproject.toml and uv.lock?

pyproject.toml is the project’s own description, the file you edit: its name and version, the Python versions it supports, and its dependencies as ranges such as rich>=15.0.0, which say what would be acceptable. uv.lock is written by uv: the exact version of every package the project installs, its dependencies’ dependencies included, so that every computer and every later install gets the same set. You change pyproject.toml yourself or with uv add, and you never edit uv.lock by hand; both are committed. When you want newer versions, you upgrade the lock on purpose, with uv lock --upgrade-package, and test the result before you commit it.

Two harder questions start from this lesson: a build that broke over a weekend without a code change, and a team whose tools are installed in the wrong places. Work out your first step before you open each one:

Key takeaways

• uv manages a project from pyproject.toml: uv init, uv add and uv run, and before every run it checks that uv.lock and .venv are up to date.
• pyproject.toml holds ranges of acceptable versions; uv.lock records one exact set, dependencies included, and is committed so that everyone installs the same packages.
• Inline script metadata is a # /// script comment block with requires-python and dependencies; uv run and pipx run read it, while plain python3 ignores it.
• pipx install and uv tool install give each command-line application its own environment and put only its commands on your PATH; tools that import your project belong in the project.
• uv and pipx automate the steps of venv and pip, which still work on every computer.