Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Virtual Environments

uv and Modern Environment Management

Use uv to install Python versions, create environments, add dependencies and run commands, and learn how its lock file works with a live parsing example.

uv is a fast Python package and project manager written in Rust. It replaces several tools at once: pip and pip-tools (installing and locking), venv and virtualenv (environments), pyenv (Python versions), pipx (command-line tools) and, for many projects, build, twine and Poetry-style project management. It does not invent new formats: it reads and writes the standard pyproject.toml, creates ordinary virtual environments and installs ordinary wheels.

Everything in this lesson that touches the shell is a read-only block, because uv is a native program that cannot run in the browser. The live examples parse and process the same files uv produces, so you will see what is inside them.

Why people switch

  • Speed. Resolution and installation are often ten to a hundred times faster than pip, thanks to parallel downloads and a global cache that is hard-linked into environments.
  • One tool. Fewer moving parts to install and explain.
  • Reproducibility by default. uv lock records exact versions and hashes in uv.lock, and uv sync makes the environment match it.
  • Python on demand. uv python install 3.13 downloads an interpreter; no system package or compiling needed.

Two modes: project and pip-compatible

uv can behave like a drop-in faster pip, or as a project manager. Pick the one that matches your habits.

The pip-compatible interface

Terminal
uv venv                           # create .venv (fast)
uv venv --python 3.12             # choose the interpreter
uv pip install requests           # into the active/.venv environment
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt   # like pip-compile
uv pip sync requirements.txt      # make the environment exactly match
uv pip list

Your existing commands keep working with uv pip in front. This is the gentlest way to adopt it.

The project interface

Terminal
uv init demo-app                  # new project with pyproject.toml
cd demo-app
uv add requests "rich>=13"        # edits pyproject.toml, locks, installs
uv add --dev pytest ruff          # development-only group
uv remove rich
uv lock                           # (re)compute uv.lock
uv sync                           # create/refresh .venv from the lock
uv run python main.py             # run inside the project environment
uv run pytest
uv tree                           # dependency tree

uv run creates the environment if it is missing and syncs it before running, so you never activate anything. The project's files after uv init and uv add are:

TEXT
demo-app/
  pyproject.toml     <- metadata + dependencies (you and uv edit this)
  uv.lock            <- exact resolved versions + hashes (commit this)
  .python-version    <- the interpreter version for this project
  .venv/             <- generated environment (ignore this)
  main.py

Managing Python itself

Terminal
uv python list                    # available and installed versions
uv python install 3.13 3.12       # download interpreters
uv python pin 3.12                # write .python-version
uv run --python 3.11 script.py    # try another version once

Interpreters live in uv's own directory, so nothing touches the system Python.

Tools and scripts

Terminal
uv tool install ruff              # a CLI in its own environment, on your PATH
uvx ruff check .                  # run once without installing (like pipx run)
uv run --with rich script.py      # add a temporary dependency

Single scripts can carry their own dependencies using the inline metadata block (PEP 723) from the tooling lesson. uv add --script tool.py requests writes it for you, and uv run tool.py creates a throwaway environment.

Inside uv.lock

The lock file is TOML. It lists each package with its exact version, where it came from, the hashes of its files, and what it depends on. Because every tool in the family reads a fixed format, you can inspect or analyze it with a few lines of Python. The snippet below is a trimmed, realistic example.

Python Reading a uv.lock-style file with tomllib

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The real file also stores a sdist and wheels entry with URLs and sha256 hashes for every package, which is what makes uv sync safe and repeatable.

Why the lock file matters

pyproject.toml says "requests, any recent version". uv.lock says "exactly requests 2.32.3, with these hashes, and these exact versions of its four dependencies". Anyone who runs uv sync gets the same tree. When you want newer versions, you ask for them explicitly with uv lock --upgrade or uv lock --upgrade-package requests, and the diff in the lock file shows exactly what changed.

flowchart LR
    A["pyproject.toml<br/>(ranges: what you want)"] -- "uv lock" --> B["uv.lock<br/>(exact versions + hashes)"]
    B -- "uv sync" --> C[".venv<br/>(installed environment)"]
    C -- "uv run" --> D["your code runs"]

You edit the left, uv derives the middle and right. Commit the first two; ignore the environment.

Comparing the old and new workflows

Python The same job in two workflows

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

uv is not the only good answer. Poetry, PDM and Hatch offer the same project-centred workflow with different file layouts or plugin systems, and pip plus venv stays perfectly valid. What matters is that your project is described by standard files, so you can change tools later without rewriting code.

Interoperating with other tools

  • Teammates who use plain pip can run uv export --format requirements-txt > requirements.txt to produce a pinned requirements file from the lock.
  • In Docker and CI, uv sync --frozen (use the lock exactly, never re-resolve) is the fast, reproducible install.
  • uv build and uv publish build and upload distributions, covered in the next chapters.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the purpose of uv.lock?

    pyproject.toml holds your loose requirements; uv.lock holds the exact resolution. Commit both.
  2. 2. What does uv run pytest do compared with activating a venv and running pytest?

    uv run handles the environment for you, so activation is unnecessary.
  3. 3. Which command installs a specific Python interpreter without touching the system Python?

    uv downloads managed interpreters into its own directory.
  4. 4. Which belongs in version control?

    The environment is generated. The project file and lock are the sources of truth.

Summary

  • uv unifies installing, environments, Python versions, locking, running, building and publishing, using standard files.
  • Use uv pip ... as a fast drop-in for pip, or uv init, uv add, uv sync, uv run for a full project workflow.
  • uv.lock is TOML with exact versions, sources and hashes; you can read it with tomllib.
  • uv run removes the need for activation.
  • uv sync --frozen is the reproducible install for CI and containers.
  • Commit pyproject.toml and uv.lock; never commit .venv.

Next: Freezing Requirements and Reproducibility