Modern Project Tooling with uv

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

uv

A fast all-in-one Python project and package manager from Astral.

pyproject.toml

The project's settings file: name, version, Python needed, dependencies, tool settings.

uv.lock

A generated file listing the exact versions (with hashes) of every package the project uses.

Lock file

A file recording the exact result of dependency resolution, so everyone installs the same thing.

Resolution

Working out one set of package versions that satisfies every rule at once.

Sync

Make the installed environment match what the lock file says.

uvx

Run a command-line tool from PyPI in a temporary environment. Same as uv tool run.

.python-version

A one-line file naming the Python version the project should use.

Rust

A fast compiled language. uv is written in it, which is why it is so quick.

1. 1

   Predict the file

   In the first example, add a third entry to after's dependency list by hand ("rich>=13") and run it. This is exactly what uv add rich would do to the text, plus the install step.

2. 2

   Try uv on your computer

   Install uv (first walkthrough step). Then run uv init demo, cd demo, uv add rich, and make main.py print something with from rich import print. Run it with uv run main.py. Delete the .venv folder and run it again: uv rebuilds it from uv.lock.

3. 3

   Run a tool without installing

   Run uvx ruff --help in any folder. Nothing is added to a project. That is the "try a tool once" use of uvx.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

dependencies = [
    "httpx>=0.28",
    "rich>=13",     # added by hand, not in uv.lock yet
]

1. 1

   uv is a Python project and package manager written in Rust by Astral (the makers of Ruff). It is much faster than pip and covers jobs that used to need several tools: pip (install packages), venv (environments), pyenv (install and switch Python versions), pipx (run command-line tools in isolation) and pip-tools (lock files). Many new Python and AI projects now start with it. It is not part of Python itself: you install it once (the first walkthrough step shows how). Like everything in Topic 6.5, you type uv commands into a terminal.

2. 2

   A project starts with uv init myproject, which makes a folder with a pyproject.toml (the project's description, Topic 6.7), a small main.py, a README.md, and a .python-version file. Then uv add httpx does three things at once: it adds httpx to [project] dependencies in pyproject.toml, creates .venv/ (the private folder of packages from Topic 6.5) if it does not exist, and installs the package into it. uv remove httpx undoes it.

3. 3

   uv run main.py runs a command inside the project's environment, creating or updating the environment first if it is out of date. You never need to activate anything: uv run python, uv run pytest and uv run main.py always use the right Python and the right packages. This removes the "forgot to activate" and "installed in the wrong place" classes of bug.

4. 4

   uv.lock is the key file. pyproject.toml records what you *asked for* (httpx>=0.28). uv.lock records what was *actually chosen*: every package, including indirect ones (packages that your packages need), at exact versions, with file hashes (a hash is a fingerprint of a file, Topic 6.9). Commit it, which means: save it into git with the rest of the project (see the Git course). uv sync makes .venv/ match the lock exactly, on any machine, and uv lock refreshes the lock from pyproject.toml. This is what makes "it works on my machine" true on every machine.

5. 5

   uv also manages Python itself. uv python install 3.13 downloads a Python build and keeps it for uv's use; uv python pin 3.13 writes a .python-version file so the whole team uses the same one; requires-python in pyproject.toml states what the project supports. You no longer depend on whatever Python your operating system happens to ship.

6. 6

   For tools rather than projects, uvx ruff check . (short for uv tool run) runs a command-line tool from PyPI in a temporary isolated environment, with nothing to install first; uv tool install ruff keeps it available everywhere. For older workflows, uv venv makes a bare venv and uv pip install -r requirements.txt is a faster drop-in for pip. Everything in the earlier topic (Topic 6.5) still applies: uv automates it.

• ↔

  uv vs plain pip and venv. uv is faster, gives a real lock file and manages Python versions, but it is one more tool to install and learn, and some older workflows and documentation still assume pip. The standard files it uses mean you can switch back at any time.

• ↔

  Lock everything vs leave ranges loose. A lock gives reproducibility at the cost of occasionally updating (uv lock --upgrade) to receive fixes. Loose ranges get fixes automatically but make builds change without a commit.

• Done when you can start a project with uv init, add a package with uv add and run code with uv run.

• Done when you can explain what uv.lock is and why it is committed.

• Done when you can describe what uv sync does on a fresh clone.

• Done when you can pin and install a Python version with uv.

• Done when you can translate pip install, python -m venv, pyenv and pipx into uv commands.