A no nonsense guide to UV (a Python Package Manager)

UV, a modern Python package manager, comes from an unexpected place — it’s written in Rust. It's 10-100 times faster than traditional package managers. However, its true strength lies in addressing long-standing issues in Python package managers, such as complex dependency resolution, inefficient virtual environment handling, and fragmented tooling, offering a more reliable and streamlined experience for developers. It’s designed to be a drop-in replacement for pip, virtualenv, pip-tools, and sometimes even Poetry.

Why Use UV?

• Instant environment creation
• Fast, deterministic dependency resolution
• Built-in virtualenv management
• Lockfile support (uv.lock)
• Built-in CLI tool isolation (uvx)
• Python version management via .python-version
• Single binary, no runtime deps

Think of it as: pip + virtualenv + pip-tools + pyenv + parts of Poetry + parts of Conda, all in one CLI tool — but up to 100x faster.

Install UV with Astral's Installer:

curl -Ls https://astral.sh/uv/install.sh | bash

Initialize a new project

uv init

This command creates a pyproject.toml and .venv with your current Python version. uv init can prompt for additional project metadata.

Add Dependencies

uv add requests

Run your project in the environment

uv pip list
uv pip freeze
uv run main.py

You can also activate the venv manually

uv venv .venv  
source .venv/bin/activate

It's compatible with existing pip projects or requirements.txt

You can still install traditional requirements.txt:

uv pip install -r requirements.txt

Install from lockfile

uv install

This installs all dependencies based on pyproject.toml and uv.lock

Upgrade dependencies

uv update

Resolves and upgrades all packages, updating the lockfile.

Okay so far what do we have?

$ tree
├── main.py
├── pyproject.toml
├── .python-version
├── README.md
└── uv.lock

Using Any Python Version with uv (even if it's not installed)

One of UV’s most powerful features is how it handles Python versions seamlessly — even if you don’t have that version installed locally.

uv venv -p 3.6 .venv

• This will create a virtual environment using Python 3.6.
• If you don’t have Python 3.6 installed, UV will:
  • Automatically detect that it's missing.
  • Suggest installing it via pyenv, which UV supports natively.
  • Use .python-version to track which Python version the project is using.

Switching Python Versions Per Project

You can use .python-version manually:

echo "3.12.0" > .python-version
uv venv

UV reads the version, creates the venv with that interpreter, and tracks everything in pyproject.toml

Removing Package

uv remove requests 

Cleanup

rm -rf .venv uv.lock

This makes UV fully self-contained and version-aware, solving one of the biggest pain points in Python development.