UV — An Ultimate Python Package Manager: The Beginner's Guide
This guide will walk you through the basics of UV, helping you get started with this exciting new tool.
What Makes UV Special?
UV is a Rust-based Python package manager aiming to replace pip with significant speed improvements (often an order of magnitude faster) and a drop-in user experience. It offers built-in virtual environment management and is evolving into a complete project management solution. Developed by Astral, UV is open-source and can manage multiple Python versions, cross-platform lockfiles, and single-file script dependencies.
Installation
UV is distributed as a single binary.
Recommended (standalone installer):
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
Alternative (via pip):
pip install uv
If you use pip, make sure the directory where pip installs executables is on your system PATH so the uv command is available globally.
Getting Started
Checking Your UV Version
After installation, verify UV is installed and functional:
uv --version
Basic Usage
Creating a Virtual Environment
To start a new project with UV, navigate to your project directory and create a virtual environment:
uv venv .venv
This command creates a .venv directory in your project folder, isolating your project’s dependencies. Activate the virtual environment:
# Linux/macOS
source .venv/bin/activate
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
:: Windows (cmd)
.\.venv\Scripts\activate.bat
You can also specify a Python version:
uv venv --python 3.12 .venv
Installing Packages
Use uv pip as a drop-in replacement for pip:
uv pip install requests
From a requirements.txt:
uv pip install -r requirements.txt
Alternative: uv add
If you use UV to manage your pyproject.toml (see below), you can add dependencies with:
uv add requests
Initialize the project first with uv init (see below).
Running Python
Prefer running code through UV so it uses the right environment automatically:
uv run python your_script.py
For PEP 723 inline-dependency scripts (see below), you can simply run the script file directly.
Listing Installed Packages
uv pip list
Uninstalling Packages
uv pip uninstall requests
Project Management with UV
UV can manage your project dependencies and lockfiles using pyproject.toml.
Initializing a Project
uv init
This creates a basic pyproject.toml in your project’s root.
Adding Dependencies
uv add flask
This adds flask to pyproject.toml and creates/updates a uv.lock file. You can explicitly (re)generate the lockfile with:
uv lock
Syncing Dependencies
Ensure your virtual environment matches pyproject.toml and uv.lock:
uv sync
Advanced Usage
Running Tools in Isolated Environments (uv tool run / uvx)
UV offers uv tool run, aliased as uvx, similar to pipx. It installs and runs command-line tools in their own isolated environment:
uv tool run cowsay -t "Hello world"
# short alias
uvx cowsay -t "Hello world"
You can include extras for the tool environment. For example:
uvx --with mkdocs-material mkdocs
Or install a tool persistently:
uv tool install ruff
uv tool upgrade --all
Single-File Script Execution with PEP 723
You can define a script’s dependencies directly in the file using PEP 723 inline metadata. Use the documented shebang:
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.9"
# dependencies = [
# "requests"
# ]
# ///
import requests
response = requests.get("https://www.example.com")
print(response.status_code)
Save as my_script.py, make it executable, and run:
chmod +x my_script.py
./my_script.py
UV will create an isolated environment (if needed), install dependencies, and execute the script.
Managing Multiple Python Versions
UV can manage Python runtimes:
# List available versions
uv python list
# Install a specific version
uv python install 3.13
# Run with a specific interpreter
uv run --python 3.13 your_script.py
Conclusion
UV is a promising tool for managing Python packages and projects. Its speed and modern features make it a compelling alternative to pip. Give it a try and see how it can improve your Python workflow! Since UV is actively developed, keep an eye on the official docs for the latest features and updates.