Skip to content

uv

uv manages Python versions and packages. Its project workflow can keep a dependency lockfile and a separate environment for the app.

Visit uv

Which Python and packages will your project use?

Python runs the app. uv can select or obtain a Python version and install the packages the project needs. A project’s pyproject.toml can declare which Python versions it supports and which packages it needs.

A .python-version file can request a particular Python version for day-to-day work. Check that request against the supported range. The interpreter that runs your app is a separate choice from the version of uv you installed.

When can uv change your project environment?

uv.lock records the package choices for supported Python versions and platforms. A project command such as uv run can update the lockfile and synchronize the environment before running your command. Syncing means installing the required packages into the project environment.

Use the project’s documented lock check when you want the build to stop if the lockfile no longer matches. The locked option rejects a stale lockfile instead of updating it. The frozen option skips that consistency check. A normal uv sync removes packages the project did not select. Even a locked sync can still install or remove packages in the environment.

Can you inspect a version mismatch without installing anything?

Use three invented file snippets on paper. Leave your terminal, project and package sources untouched.

  1. Separate the runtime from the packages
    Write that the project supports Python 3.11 through 3.13 and requests Python 3.12. Mark which line defines the supported range and which one selects your everyday version.
  2. Spot a dependency mismatch
    Write that pyproject.toml now requires the fictional demo-widget at version 2 or newer while uv.lock has version 1. A locked check should stop. An intentional dependency update should change the lockfile and be reviewed.
  3. Decide what the next machine needs
    List pyproject.toml, the requested Python version and uv.lock. Write down which package source the project uses. Keep credentials separate and recreate the environment on the destination machine.

What should you check on a new machine?

Check the official uv installer and platform requirements. Astral documents standalone installers for macOS, Linux and Windows, and alternatives such as an isolated PyPI install with pipx. Follow the version and install route your project documents.

Keep the project files and lockfile. uv can export dependency selections to formats such as requirements.txt or pylock.toml for a workflow that expects them. Check which format the destination understands and whether its Python version and platform are covered. A lockfile is a record of selected packages, so you still need access to the intended sources.