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 (10x or even more) and 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
Before diving in, you'll need to install UV. Since UV is written in Rust, it's distributed as a single binary. You can install it using pip:
pip install uv
It's recommended to add location where pip installs binaries to your systems PATH enviroment variable to make uv command available globally.
Getting Started
Checking Your UV Version
After installation, verify UV is installed and functional by checking its version:
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:
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
You can also specify a specific Python version to use for the virtual environment:
uv venv --python 3.12 .venv
Installing Packages
To install packages, use the uv pip install command:
uv pip install requests
To install from a requirements.txt file:
uv pip install -r requirements.txt
Alternative: uv add
If you use uv to manage your pyproject.toml file (see below), you can also use the uv add command:
uv add requests
It's important to have uv project managed initalized first (see below).
Running Python
To run a python script use the standard python, python your_script.py.
Listing Installed Packages
To see a list of all packages installed in your virtual environment, use:
uv pip list
Uninstalling Packages
To uninstall packages:
uv pip uninstall requests
Project Management with UV
UV can also manage your project dependencies and lockfiles using pyproject.toml.
Initializing a Project
To create a pyproject.toml file, use:
uv init
This will create a basic pyproject.toml file in your project's root directory.
Adding Dependencies
You can add dependencies to your project using uv add:
uv add flask
This command will add flask to your pyproject.toml file and create (or update) a uv.lock file.
Syncing Dependencies
To ensure your virtual environment matches the dependencies specified in your pyproject.toml and uv.lock files, use:
uv sync
Advanced Usage
Running Tools in Isolated Environments (uv tool run)
UV offers a uv tool run command, aliased to uvx, which is similar to pipx. It runs a command-line tool in its own isolated virtual environment:
uv tool run cowsay -t "Hello world"
# short version
uvx cowsay -t "Hello world"
This will install cowsay (if it's not already installed) into a dedicated environment and then run it. You can also install extras:
uvx --with notebook jupyter lab
Single-File Script Execution with PEP 723
You can define a script's dependencies directly within the script itself using PEP 723 inline metadata:
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.9"
# dependencies = [
# "requests"
# ]
# ///
import requests
response = requests.get("https://www.example.com")
print(response.status_code)
Save this as my_script.py, make it executable (chmod +x my_script.py), and run it directly:
./my_script.py
UV will automatically create a virtual environment, install the dependencies, and execute the script.
Managing Multiple Python Versions
UV can manage multiple Python versions on your system. You can list available versions:
uv python list
And install specific versions:
uv python install 3.13
You then select the Python version to used with --python parameter:
uv run --python 3.13 your_script.py
Conclusion
UV is a promising new 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 development workflow! As the tool is actively being developed, keep an eye on the official documentation for the latest features and updates.