Introducing uv: Next-Gen Python Package Manager

Python evolution has been closely tied to advancements in package management, from manual installations to tools like pip and poetry. However, as projects grow in complexity, traditional tools often fall short in speed and efficiency.

uv is a cutting-edge Python package and project manager built with Rust, aims to change that. Combining the functionality of tools like pip, poetry, and virtualenv, uv streamlines tasks like dependency management, script execution, and project building—all with exceptional performance. Its seamless compatibility with pip commands, requiring no additional learning curve.

In this tutorial, we will explore how to install uv and make the most of its features. From setting up a project and managing dependencies to running scripts and leveraging its enhanced pip interface.

Getting Started

Table of contents

• pip limitations
• What is uv
• Key features of uv
• Benchmarks
• Installation
• Creating virtual environments
• Building a flask app using uv
• Installing python with uv
• Tools
• Cheatsheet
• Current Limitations

pip limitations

Pip is a widely used package management system written in Python, designed to install and manage software packages. However, despite its popularity, it is often criticized for being one of the slowest package management tools for Python. Complaints about “pip install being slow” are so common that they frequently appear in developer forums and threads.

One significant drawback of pip is its susceptibility to dependency smells, which occur when dependency configuration files are poorly written or maintained. These issues can lead to serious consequences, such as increased complexity and reduced maintainability of projects.

Another limitation of pip is its inability to consistently match Python code accurately when restoring runtime environments. This mismatch can result in a low success rate for dependency inference, making it challenging to reliably recreate project environments.

What is uv

uv is a modern, high-performance Python package manager, developed by the creators of ruff and written in Rust. Designed as a drop-in replacement for pip and pip-tools, it delivers exceptional speed and compatibility with existing tools.

Key features include support for editable installs, Git and URL dependencies, constraint files, custom indexes, and more. uv’s standards-compliant virtual environments work seamlessly with other tools, avoiding lock-in or customization. It is cross-platform, supporting Linux, Windows, and macOS, and has been tested extensively against the PyPI index.

Focusing on simplicity, speed, and reliability, uv addresses common developer pain points like slow installations, version conflicts, and complex dependency management, offering an intuitive solution for modern Python development.

Key features of uv

• ⚖️ Drop-in Replacement: Seamlessly replaces pip, pip-tools, virtualenv, and other tools with full compatibility.
• ⚡ Blazing Speed: 10–100x faster than traditional tools like pip, pip-compile, and pip-sync.
• 💾 Disk-Space Efficient: Utilizes a global cache for dependency deduplication, saving storage.
• 🐍 Flexible Installation: Installable via curl, pip, or pipx without requiring Rust or Python.
• 🧪 Thoroughly Tested: Proven performance at scale with the top 10,000 PyPI packages.
• 🖥️ Cross-Platform Support: Fully compatible with macOS, Linux, and Windows.
• 🔩 Advanced Dependency Management: Features include dependency version overrides, alternative resolution strategies, and a conflict-tracking resolver.
• ⁉️ Clear Error Messaging: Best-in-class error handling ensures developers can resolve conflicts efficiently.
• 🤝 Modern Python Features: Supports editable installs, Git dependencies, direct URLs, local dependencies, constraint files, and more.
• 🚀 Unified Tooling: Combines the functionality of tools like pip, pipx, poetry, pyenv, twine, and more into a single solution.
• 🛠️ Application and Script Management: Installs and manages Python versions, runs scripts with inline dependency metadata, and supports comprehensive project workflows.
• 🗂️ Universal Lockfile: Simplifies project management with consistent and portable lockfiles.
• 🏢 Workspace Support: Handles scalable projects with Cargo-style workspace management.

Benchmarks

source: https://blog.kusho.ai/uv-pip-killer-or-yet-another-package-manager
Resolving (left) and installing (right) dependencies using a warm cache, simulating the process of recreating a virtual environment or adding a new dependency to an existing project.

source: https://blog.kusho.ai/uv-pip-killer-or-yet-another-package-manager
Resolving (left) and installing (right) dependencies with a cold cache simulate execution in a clean environment. Without caching, uv is 8–10x faster than pip and pip-tools, and with a warm cache, it achieves speeds 80–115x faster.

source: https://blog.kusho.ai/uv-pip-killer-or-yet-another-package-manager
Creating a virtual environment with (left) and without (right) seed packages like pip and setuptools. uv is approximately 80x faster than python -m venv and 7x faster than virtualenv, all while operating independently of Python.

Installation

Installing uv is quick and straightforward. You can opt for standalone installers or install it directly from PyPI.

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# With pip.
pip install uv

# With pipx.
pipx install uv

# With Homebrew.
brew install uv

# With Pacman.
pacman -S uv

Before using uv, we have to add the uv path to environment variables.
For Linux and macOS, modify the PATH environment variable using the following command in the terminal:

export PATH="$HOME/.local/bin:$PATH"

For windows, To add a directory to the PATH environment variable for both user and system on Windows, search for Environment Variables in the search panel. Under User variables / System variables, select the Path variable, click Edit, then click New and add the desired path.

%USERPROFILE%\.local\bin

After the installation, run the uv command in the terminal to verify that it has been installed correctly.

Creating virtual environments

Creating a virtual environment with uv is simple and straightforward. Use the following command, along with your desired environment name, to create it.

uv venv

• Run the following command to activate the virtual environment.

# On macOS and Linux.
source .venv/bin/activate

# On Windows.
.venv\Scripts\activate

Installing packages

Installing packages into the virtual environment follows a familiar process. The various installation methods are given below.

uv pip install flask                # Install Flask.
uv pip install -r requirements.txt  # Install from a requirements.txt file.
uv pip install -e .                 # Install current project in editable mode.
uv pip install "package @ ."        # Install current project from disk
uv pip install "flask[dotenv]"      # Install Flask with "dotenv" extra.

To synchronize the locked dependencies with the virtual environment, use the following command:

uv pip sync requirements.txt  # Install dependencies from a requirements.txt file.

uv supports a variety of command-line arguments similar to those of existing tools, including -r requirements.txt, -c constraints.txt, -e ., --index-url, and more.

Building a flask app using uv

Let’s explore some project-related commands with uv. Start by initializing a Python project named “sample-project.”

uv init sample-project

Navigate to the sample-project directory. uv initializes the project with essential files such as app.py, requirements.txt, README.md, and more.

Use the run command to execute the sample Python file. This process first creates the virtual environment folder and then runs the Python file.

uv run hello.py

Install flask

Add Flask to your project dependencies.

uv add flask

Create the Flask Application

Create a new one and write the following code.

from flask import Flask

app = Flask(__name__)

@app.route('/', methods=['GET'])
def hello_world():
    return {"message": "Hello, World!"}, 200

if __name__ == '__main__':
    app.run(debug=True)

Run the app

Use the uv run command to execute the application.

uv run app.py

Open a browser or use a tool like curl or Postman to send a GET request.

Installing python with uv

Using uv to install Python is optional, as it works seamlessly with existing Python installations. However, if installing Python through uv is preferred, it can be done with a straightforward command:

uv python install 3.12

This approach is often more convenient and reliable compared to traditional methods, as it avoids the need for managing repositories or downloading installers. Simply execute the command, and the setup is ready to use.

Tools

CLI tools can be installed and used with the uv command. For example, the huggingface_hub tools can be installed to enable pulling and pushing files to Hugging Face repositories.

• Use the following command to install huggingface_hub using uv.

uv tool install huggingface_hub

• The following command displays all the installed tools:

uv tool list

Cheatsheet

Here is a quick cheatsheet for performing common operations with uv:

Current Limitations

Even though uv offers a fast and efficient solution for Python package management, it has some limitations:

• Incomplete pip Compatibility: Although uv supports a substantial portion of the pip interface, it does not yet cover the entire feature set. Some of these differences are intentional design choices, while others stem from uv still being in its early stages of development. For a detailed comparison, consult the pip compatibility guide.
• Platform-Specific requirements.txt: Like pip-compile, uv generates platform-specific requirements.txt files. This contrasts with tools such as Poetry and PDM, which create platform-agnostic poetry.lock and pdm.lock files. Consequently, uv's requirements.txt files may lack portability across different platforms and Python versions.

Thanks for reading this article !!

Thanks Gowri M Bhatt for reviewing the content.

If you enjoyed this article, please click on the heart button ♥ and share to help others find it!

Resources

uv - An extremely fast Python package and project manager, written in Rust | docs.astral.sh