uv - New Python Package, Project, and Environment Manager

Good things about Python uv

Page content

Python uv (pronounced “you-vee”) is a modern, high-performance Python package and project manager written in Rust. It is designed as a drop-in replacement for traditional Python package management tools such as pip, pip-tools, virtualenv, pipx, and pyenv, aiming to simplify and accelerate Python development workflows

uv is developed by Astral, the team behind the popular Python linter Ruff, and is designed to address common pain points in the Python ecosystem—such as slow installations, dependency conflicts, and complex environment management—by leveraging Rust’s performance and modern software architecture.

uv python ultra-violet spa

Key Features of uv

  • Exceptional Speed: uv is significantly faster than traditional tools—typically 8–10x faster than pip without caching, and up to 80–115x faster with a warm cache.
  • All-in-One Tool: Combines package installation, dependency resolution, virtual environment management, Python version management, project scaffolding, and script execution in a single tool.
  • Compatibility: Offers a pip-compatible command-line interface, making it easy to adopt without a steep learning curve.
  • Robust Dependency Management: Provides precise dependency resolution and lockfile support for reproducible environments.
  • Automatic Virtual Environments: Creates and manages virtual environments automatically, reducing manual setup.
  • Cross-Platform Support: Works on macOS, Linux, and Windows.
  • Standalone Installation: Can be installed without requiring Python or Rust, using a simple installer or curl.

uv vs poetry vs pdm vs pip performance comparison

Still not sure Why Use uv?

  • Performance: Dramatically reduces package installation and dependency resolution times.
  • Simplicity: Unifies multiple tools into one, streamlining project setup and management.
  • Reliability: Delivers consistent, reproducible environments with clear error messages and conflict resolution.
  • Modern Standards: Supports pyproject.toml for project configuration, aligning with current Python packaging standards.

Example Use Cases

Let’s try something exciting!

  • Starting a New Project:
uv init myproject
cd myproject
uv add requests
uv run python script.py

This creates a project directory, sets up a virtual environment, installs dependencies, and runs scripts in an isolated environment.

  • Managing Scripts with Inline Dependencies:
uv add --script script.py requests
uv run script.py

uv can manage dependencies for single-file scripts without separate requirements files.

Comparison to Traditional Tools

Feature uv pip/virtualenv Poetry
Speed Very fast Slow Moderate
Virtual Environments Automatic Manual Automatic
Dependency Resolution Advanced Basic Advanced
Python Version Management Yes No (requires pyenv) No
Lockfile Support Yes No (requires pip-tools) Yes
Script Execution Integrated No Limited

How can I install and start using UV on my system

To install and start using uv on your system, follow these straightforward steps:

Installation

  1. Standalone Installer (Recommended)
    • Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

Or, if you prefer wget:

wget -qO- https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • Specific Version: You can request a specific version by including it in the URL, e.g., https://astral.sh/uv/0.7.15/install.sh.
  1. Alternative: Install via pip (if you have Python installed)
pip install uv

Note: This method is less recommended for system-wide access unless you know what you are doing, as it may clutter your system Python environment.

  1. Install via pipx (for isolated, user-wide installation)
pipx install uv

This method is cleaner for global access if you already use pipx.

Getting Started

To Check Installation - Run:

uv

You should see a help menu confirming uv is installed and ready.

To Create and Activate a Virtual Environment

  • Create a venv:
uv venv test
  • Activate it on Linux/macOS:
source test/bin/activate
  • Activate it on Windows:
.\test\Scripts\activate

Now you can use uv pip install to install packages in this environment.

Initialize a New Project

uv init

This creates a pyproject.toml and .gitignore for your project.

Add Dependencies

Add a package:

uv add

This updates pyproject.toml and generates/updates the lockfile.

Sync Dependencies

Install all dependencies in your environment:

uv sync

Or, use the pip-compatible interface:

uv pip install

This ensures all dependencies are installed according to your lockfile.

Run Scripts

Use:

uv run script.py

This automatically manages the environment and dependencies for your script.

Shell Integration (Optional)

For a smoother workflow, you can add shell integration to your .zshrc or .bashrc to automatically activate a default virtual environment and alias pip to uv pip.

With these steps, you’ll have uv installed and be ready to manage your Python projects with speed and ease.

Installing Specific Python Versions

You can use uv to install specific Python versions and manage them for your projects.

  • Install the latest stable Python version: 
    uv python install
    This command downloads and installs the most recent stable Python version available.
  • Install a specific version: 
    uv python install 3.12
    This installs the latest patch release of Python 3.12 (e.g., 3.12.3).
  • Install an exact patch version: 
    uv python install 3.12.3
    This installs exactly Python 3.12.3.
  • Install multiple versions: 
    uv python install 3.9 3.10 3.11
    This installs Python 3.9, 3.10, and 3.11.
  • Install a version that matches a constraint: 
    uv python install '>=3.8,=3.11"
    This changes the project’s Python version requirement.

Additional Notes

Automatic Downloads: By default, uv will automatically download and install required Python versions if they are not found on your system.

System Python: uv can use existing Python installations if present, or you can force it to use system Python with the --no-managed-python flag.

Upgrading: You can upgrade uv-managed Python versions to the latest patch release with:

uv python upgrade 3.12

Or upgrade all installed versions:

uv python upgrade

Upgrading across minor versions (e.g., 3.12 to 3.13) is not supported.

In summary, uv provides flexible and powerful tools for installing, managing, and using specific Python versions in your projects.

How does UV discover available Python interpreters on different systems

UV discovers available Python interpreters on different systems by checking a set of well-defined locations and querying each candidate for its version metadata. Here’s how it works:

  • Managed Python Installations:
    UV first looks in the directory specified by the UV_PYTHON_INSTALL_DIR environment variable, where it stores its own managed Python versions.
  • System PATH:
    On macOS and Linux, UV checks for executables named python, python3, or python3.x (where x is a version number) in directories listed in the system PATH. On Windows, it looks for python.exe.
  • Windows-Specific Locations:
    On Windows, UV also checks the Windows registry and Microsoft Store Python interpreters using the output from py --list-paths.
  • Virtual Environments:
    If a virtual environment is active or specified, UV checks the interpreter in that environment for compatibility before searching elsewhere.
  • Metadata Query:
    Each discovered executable is queried for its version metadata. Only executables that match the requested version (or version constraint) are considered. Non-executable files are ignored.
  • Preference and Fallback:
    By default, UV prefers system Python installations, but you can adjust this with options to prefer managed or only use managed/system versions. If no suitable interpreter is found, UV can download and install the required version.

This robust discovery process ensures UV can reliably locate and use the correct Python interpreter across different operating systems and environments.