Managing Python dependencies with uv

uv manages the dependencies and the virtual environment of a Python project. Everything rests on three files, always in the same order:

pyproject.toml ──uv lock──▶ uv.lock ──uv sync──▶ .venv/
what you want              exact versions       what is installed
(ranges >=, <)

File	Role	In git
pyproject.toml	Wanted dependencies, with version ranges	Yes
uv.lock	Exact resolved versions, for every platform	Yes
.venv/	Environment installed on the machine	No

Rule of thumb

Always commit pyproject.toml and uv.lock together.

On the development machine

Step	Command
Add a dependency	uv add httpx
Add a dev dependency	uv add --dev pytest
Remove a dependency	uv remove httpx
After a git pull	uv sync
pyproject.toml edited by hand	uv lock, then uv sync
Upgrade one package	uv lock --upgrade-package httpx
Upgrade everything	uv lock --upgrade
Run a command	uv run pytest
Before committing	uv lock --check

uv add and uv remove update all three layers at once. uv run syncs the .venv before running the command.

If the project declares its dev tools as optional dependencies ([project.optional-dependencies]) rather than as a dev group, use uv add --optional dev pytest and uv sync --extra dev.

In continuous integration

bash

uv sync --locked
uv run pytest

On the server

bash

uv cache prune --ci
uv sync --locked --no-dev

uv cache prune --ci empties the cache of downloaded packages. Without it, the cache keeps every installed version and ends up filling the disk.

--locked or --frozen

• --locked installs into the .venv the packages at the exact versions listed in uv.lock, and fails if it no longer matches pyproject.toml. Use it in CI and in production: a pyproject.toml committed without its lock is caught.
• --frozen also installs the versions from uv.lock, but without checking that it still matches pyproject.toml. Avoid it, except in special cases.