uv Python Package Manager: A Practical Starter Guide

What the uv Python package manager is

uv is a Python package and project manager from Astral, the team behind the Ruff linter. It is written in Rust and aims to replace several separate tools with one program: pip for installing packages, venv or virtualenv for environments, pyenv for Python versions, and pipx for command-line tools. The big selling point is speed, since installs and dependency resolution are much quicker than with pip.

If you are used to the classic workflow, my pip Python package manager guide covers the basics that uv builds on. Everything below assumes you already know why a virtual environment matters.

Install uv

On macOS and Linux you can use the official install script, or Homebrew on a Mac:

brew install uv

Other options include pipx install uv or the standalone installer from the Astral documentation. Check the current install command on the official site before running a script. Confirm it worked with uv --version.

Start a new project

uv init my-project
cd my-project

This creates a pyproject.toml, a starter main.py and a pinned Python version file. Then add a dependency:

uv add requests

uv creates a .venv folder, installs the package, records it in pyproject.toml, and writes a uv.lock file with exact versions. Commit both files so everyone on the team gets the same environment.

Run code without activating anything

You do not have to source an activate script. Use uv run and it runs the command inside the project environment, creating or updating it first if needed:

uv run python main.py
uv run pytest

When a teammate clones the project, they run uv sync and get exactly the locked set of packages.

Manage Python versions

uv can download and manage Python itself, which removes the need for pyenv:

uv python list
uv python install 3.13
uv python pin 3.13

uv python pin writes the version into a .python-version file, and uv uses it for that project. Pick a version your dependencies support.

Use uv as a faster pip

If you have an existing project with a requirements.txt and do not want to change how it works, uv has a pip-compatible interface:

uv venv
uv pip install -r requirements.txt

This is the lowest-risk way to try it. The commands mirror pip, so you can switch back at any time.

Dependency groups and removing packages

• Dev tools: uv add --dev ruff pytest keeps test and lint tools separate from runtime dependencies.
• Remove a package: uv remove requests updates the project file and the lock.
• Update everything: uv lock --upgrade refreshes the lock file to the newest allowed versions, then uv sync applies it.

Install command-line tools

For tools you want available everywhere, such as a linter or formatter, use the tool interface instead of installing into a project:

uv tool install ruff
uvx ruff check .

uvx runs a tool in a temporary environment without installing it permanently, which is handy for one-off use.

uv vs pip vs Poetry

• pip: ships with Python and works everywhere, but needs venv and extra tools around it and has no lock file by default.
• Poetry: a mature project manager with locking and publishing. It is slower and does not manage Python versions itself.
• uv: project management, lock file, Python versions and fast installs in one tool.

If your team already has a Poetry workflow that works, there is no emergency to move. For new projects and scripts, uv is the easiest place to start.

A sensible way to adopt it

1. Install uv and try uv pip install on an existing project.
2. Use uv init for your next new project.
3. Commit uv.lock and .python-version.
4. Update your CI to run uv sync before tests.

That is a small change, and it often removes a whole class of “works on my machine” problems.