π uv β Python Package and Project Manager
4 min read
uv is a high-performance Python package manager and project toolchain, written in Rust. It consolidates functionalities from multiple tools into a single, fast, and efficient interface, aiming to replace pip, pipx, poetry, pyenv, virtualenv, pip-tools, twine, and more.
π§ Key Features
β’ Unified Tooling: Combines functionalities of multiple tools into one.
β’ Blazing Fast: 10β100x faster than pip.
β’ Cross-Platform: Supports macOS, Linux, and Windows.
β’ Minimal Dependencies: Single binary with no external dependencies.
β’ Comprehensive Project Management: Handles pyproject.toml, lockfiles, and more.
β’ Python Version Management: Install and manage multiple Python versions.
β’ Tool Installation: Install and run Python-based tools like ruff, black, etc.
β’ Script Execution: Run standalone Python scripts with inline dependencies.
βοΈ Usage
Python Version Management
β’ Install Python Versions:
bash
uv python install 3.10.7
β’ List Installed Versions:
bash
uv python list
β’ Pin Python Version for Project:
bash
uv python pin 3.10.7
β’ Uninstall Python Version:
bash
uv python uninstall 3.10.7
Virtual Environments
β’ Create a Virtual Environment:
bash
uv venv
β’ Create with Specific Python Version:
bash
uv venv --python 3.10
β’ Activate the Environment:
bash
source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
β’ Install Dependencies:
bash
uv pip install -r requirements.txt
β’ Freeze Installed Packages:
bash
uv pip freeze > requirements.txt
Project Management
β’ Initialize a New Project:
bash
uv init my-project
β’ Add a Dependency:
bash
uv add requests
β’ Remove a Dependency:
bash
uv remove requests
β’ Sync Dependencies:
bash
uv sync
β’ Generate Lockfile:
bash
uv lock
β’ Run Project Scripts:
bash
uv run script.py
β’ Build Project:
bash
uv build
β’ Publish Project:
bash
uv publish
Tool Management
β’ Install a Tool:
bash
uv tool install black
β’ Uninstall a Tool:
bash
uv tool uninstall black
β’ Run a Tool:
bash
uv tool run black .
β’ List Installed Tools:
bash
uv tool list
Running Python Scripts with Inline Dependencies
Add Inline Metadata to Your Script
To begin, you'll need to add metadata to your Python script to specify the required dependencies and Python version. This can be done using the uv add --script command:
bash
uv add --script your_script.py 'requests' 'numpy'
This command will modify your script to include a special comment block at the top, indicating the dependencies:
python
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests",
# "numpy",
# ]
# ///
Make the Script Executable
To run your script directly from the command line, add a shebang line at the very top of your script:
python
#!/usr/bin/env -S uv run --script
Ensure the script is executable:
bash
chmod +x your_script.py
Run the Script
Now, you can execute your script directly:
bash
./your_script.py
The first time you run it, uv will create an isolated virtual environment, install the specified dependencies, and execute the script. On subsequent runs, the environment is cached, leading to near-instant execution times .
π¦ Compatibility with Existing Tools
uv is designed to be compatible with existing Python tools and workflows:
β’ pyproject.toml Support: Fully supports PEP 621-compliant pyproject.toml files.
β’ requirements.txt Compatibility: Works seamlessly with requirements.txt files.
β’ pip Interface: Provides a familiar pip-like interface for package management.
β’ pipx Replacement: Can install and run Python-based tools globally, replacing pipx.
β’ pyenv Alternative: Manages multiple Python versions without the need for pyenv.
π§ͺ Example
Here's a typical workflow using uv:
bash
# Initialize a new project
uv init my-project
# Navigate into the project directory
cd my-project
# Create a virtual environment
uv venv
# Activate the environment
source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
# Add dependencies
uv add requests
# Generate lockfile
uv lock
# Install dependencies
uv sync
# Run the project script
uv run script.py