UV Ultimate Guide: The 100X Faster Python Package Manager

Most Python developers deal with fragmentation in the tools to manage environments and dependencies. There are many tools at your disposal – pip, virtualenv, Poetry, and conda. All of these tools have their constructs and requirements. However, when combined, you can quickly see how they can complicate any necessary workflows. This is where UV will help as the one true Python package manager you need.

For those unaware, UV is a modern, high-performance Python package manager written in Rust. Never mind the other tools, UV’s goal is to make use of the functionality of all these tools into one conditional experience that opens with one terminal command. UV is being developed by Astral and is intended to be benchmarked against pip, virtualenv, pip-tools, and aspects of pyenv with a goal of being a significantly faster tool in an all-in-one dependency and environment management!

What is UV?

As a black box, UV is a modern, high-performance Python package manager and installer written in Rust. It is a drop-in replacement for traditional Python package managers like pip. It provides similar or improved speed, improved reliability, and consistency with dependency resolution. UV was designed to provide solutions to some of the most visible pain points in the Python ecosystem. Long install times, dependency resolution pitfalls, and the enterprise-level complications with environment management! All of these pain points are exemplary use cases for UV, and it has a unique architecture and thoughtful implementation to achieve its fast speed and efficient package workflows. It can be 10-100 times faster than existing package management choices!

UV’s ambition is to streamline common Python development workflows by offering integrated capabilities for:

• Installing packages: Similar to pip.
• Managing environments: A replacement for virtualenv.
• Locking dependencies: Providing the functionality of pip-tools or Poetry for reproducible builds.
• Managing Python versions: Offering an alternative to pyenv.

Unlike traditional tools that operate independently, UV provides a cohesive, “batteries-included” approach to Python development. It aims to reduce the number of tools and commands developers need to manage.

Key features that make UV stand out include:

• Lightning-fast package installation and dependency resolution.
• Compatible with existing Python tools and workflows.
• Built-in virtual environment management.
• Support for modern packaging standards.
• Reliable dependency locking and reproducible environments.
• Memory-efficient operation, especially for large projects.

Whether working on small personal projects or managing large-scale Python applications, UV provides a robust and efficient solution as a Python package manager.

UV vs Poetry vs PIP + Virtualenv vs Conda: The Difference

The first question developers often ask before switching to a new tool is “How does it compare to the one I am already using?”. In the Python dependency and project management arena, pip, Poetry, Conda, and virtualenv are already the most common tools. However, UV has its own benefits among the list of Python package managers available today.

The following table highlights UV’s position among established Python management tools:

With this, we shall now explore the strengths, weaknesses, and the comparison of these tools with UV individually.

UV vs. PIP and virtualenv

Pip and virtualenv have always been separate tools for Python environment and package management. Of these, pip is specifically for packages, and virtualenv is specifically for isolated environments. Here is a quick look at their strengths and weaknesses combined:

UV’s Advantages Compared to pip + virtualenv

Here are some ways in which UV is clearly the more preferable choice among the two:

• Single Tool: UV is both for creating environments and for package installation. A single command (uv) can be used for both and reduces the overall workflow.
• Modern parallelized dependency resolver: UV’s resolver uses a modern resolver, which installs more quickly, as it will install dependencies more quickly and in parallel when possible.
• Lockfile creation (uv.lock): UV automatically created a lockfile for us, which guarantees we are installing the same package versions each time, and improves reproducibility.

Example of UV vs pip + virtualenv

When using pip + virtualenv to set up an environment and install packages, this involves:

virtualenv env
source env/bin/activate
pip install -r requirements.txt

When using UV, you would run:

uv env create
uv install

UV typically finishes installs much faster than pip + virtualenv, and guarantees the exact same package versions are installed on different machines using a generated lockfile.

Conda vs UV

A versatile and powerful environment and package manager, Conda is used quite often within the scientific community and in data science. It is intended to support all packages (not just Python packages), including system-level dependencies and system libraries that are important for executing more complex scientific computing workflows.

Here is a look at the strengths and weaknesses of Conda for Python development.

UV’s Advantages Over Conda

Here are the aspects in which UV trumps Conda:

• Lightning-Fast Package Installation and Environment Setup: UV is implemented in Rust, with optimized parallel downloading and a faster implementation of installing packages and creating environments, allowing for a substantial speedup for environments. Developers will benefit from increased productivity.
• Minimal Memory and CPU Usage: UV uses less memory and CPU resources when performing operations, making it effective on very constrained machines or within CI Pipelines where every resource usage is crucial.
• Full Compatibility with Python Packaging Standards: UV is built on the same packaging standards as all existing Python tools and formats, such as requirements.txt and PyPI indexes. This will allow developers to use UV without shifting to a new ecosystem or maintaining lists of packages.
• Easier Integration into Existing Python Workflows: Since UV is solely concerned with Python packages, it doesn’t introduce much additional complexity around system-level dependency management and integrates seamlessly with typical Python development environments.

Example of UV vs Conda

Setting up an environment using Conda typically looks like this:

conda create -n myenv python=3.9 numpy scipy
conda activate myenv

Whereas with UV, the process is:

uv env create -p python=3.9
uv install numpy scipy

Conda is a very powerful tool for scientific and data science projects because it is able to manage system-level packages and provide a variety of platforms in the same environment. However, there is some downside to using conda in terms of speed of installation and memory usage, which may be noteworthy in some cases.

In comparison, UV is especially useful in instances where installation speed, low overhead, and staying within the Python ecosystem are one’s primary concerns. Also, when the project does not have many non-Python dependencies, at which point it is still useful and advantageous to use conda.

UV vs. Poetry

Poetry is a modern all-in-one Python package manager that performs dependency management, project scaffolding, and package publishing all in an organized, opinionated manner.

Also read: How to Build a RAG Evaluator Python Package with Poetry?

Strengths of Poetry

Here are some clear strengths of Poetry:

• Strong Dependency Resolver: Poetry can handle complex version conflicts between dependencies and allows dependencies to interface smoothly together.
• Built-in Project Structure: Poetry provides project scaffolding and prescribes a project structure (layout) to make it easy to maintain a consistent project layout.
• Integrated Publishing: Poetry includes commands for publishing packages to PyPI, making publishing a breeze..
• Reproducibility: generates poetry.lock file to create reproducible environments across machines.

Weaknesses of Poetry

Some of the limitations of Poetry include:

• Opinionated Workflow: Poetry provides conventions that can reduce flexibility for developers who want to configure their project in their own way.
• Slower Dependency Resolution: Poetry’s dependency resolver can be slower than UV’s, which means it can take longer to install dependencies on large projects.
• Compatibility Issues: Poetry’s conventions occasionally come at expense of modifying what is considered a “normal” pip-based workflow that sometimes hampers integration with a combination of other tools.

UV’s Advantages Over Poetry

Here are some reasons why UV trumps Poetry as a Python package manager:

• Blazing Fast Dependency Resolution: UV utilizes rapid computation for resolving and installing dependencies through its Rust implementation, to create environments in a fraction of the time of a traditional Python package manager.
• Lightweight and Efficient: Uses very little system resources to build environments very quickly.
• Compatibility with Standard Python Packaging: Unlike poetry, which forces a developer to manage their Python environments and project according to its conventions, UV plays well with existing requirements.txt and setup.py and is extremely easy to integrate alongside pip and existing tooling.
• Flexible Project Structure: Unlike poetry, UV does not dictate any particular format, allowing devs to adopt it one step at a time, without changing how they do projects.

Example

Creating a project and adding dependencies with Poetry:

[poetry new myproject
cd myproject
poetry add requests flask
poetry install]

Poetry manages both the project structure and the environment. With UV, you can install dependencies in an already built project:

uv install requests flask

UV is about quick installs and environment management without `dictating` a structural layout, making its lack of structure quite easy to adopt step-wise.

Getting Started with UV: A Simple Guide

So you have decided to give UV a chance as your next Python package manager. Smart choice, and here is how you can go about it.

Step 1: Installing UV

You can install UV on macOS and Linux via the terminal with curl:

curl -LsSf https://astral.sh/uv/install.sh | sudo sh

On Windows, run it from PowerShell (you must run with administrator privileges):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

You can also install it using Homebrew:

brew install uv

A pip installation is supported, but not recommended. Once installed, check that it’s working by checking the version:

uv version

Step 2: Starting a New Project

To start a new project using UV, you need to navigate to the project directory that you already have or create your new one:

mkdir myproject
cd myproject
uv init

For example, if it were called uv init explore-uv, it would create a new project named explore-uv. This first command will create a project directory (explore-uv) and automatically create:

• .gitignore
• .python-version
• README.md
• hello.py (a sample file)
• pyproject.toml (main configuration file for project metadata and dependencies)

Step 3: Adding Initial Dependencies to the Project

UV combines creating an environment and adding dependencies to a project in one command: uv add

uv add scikit-learn xgboost

When you first execute uv add, UV creates a new virtual environment in the current working directory and installs the dependencies you specified. The second time you run uv add, it will use your existing virtual environment and install or update the new packages you requested.

UV manages dependencies with a timely modern dependency resolver, analysing the entire dependency graph and finding compatible versions of packages to avoid version conflicts. At the end of each add command, UV updates your pyproject.toml and uv.lock files with the versions you installed, maintaining an accurate record.

To remove a dependency and its child dependencies, run uv remove:

uv remove scikit-learn

Step 4: Running Python Scripts Using UV

Once you install your dependencies, you can run Python scripts using uv run instead of using python script.py:

uv run hello.py

This command makes certain that the script is run in the project’s virtual environment created by UV.

Managing Python Versions with UV

Here are some ways in which UV streamlines working with Python versions.

Listing Existing Python Versions

UV can detect existing or installed versions of Python on your machine:

uv python list --only-installed

This command will show a listing of every version of Python that UV finds, including ones that were installed via Conda or Homebrew.

Changing Python Versions for the Current Project

You can switch Python versions for your UV project at any point, provided the new version satisfies the requires-python specification in your pyproject.toml file (e.g., requires-python = “>=3.9”).

To set a Python version:

uv python use 3.11

This embeds the Python version in .python-version and maintains consistency. If it can’t find the requested version, UV will download and install it in ~/.local/share/uv/python. Then, UV will create a new venv in the project directory and replace the old one. After updating the Python version, you may want to reinstall your dependencies:

uv pip install -e .

If you get Permission Denied-related errors, you may need to use sudo (macOS/Linux) or run your command prompt as an administrator (Windows). A better option is to change ownership of the UV home directory:

sudo chown -R $USER ~/.local/share/uv # macOS or Linux

Check the Active Version

uv python --version

Understanding UV Tools

The UV tool also provides interfaces to manage Python packages that expose themselves as command-line tools (black, flake8, pytest…).

Black is a popular code formatter for Python that automatically reformats your code to follow a consistent style, improving readability and maintaining uniform code style across your project.

uv tool run tells UV to run a tool, and black is the tool name (Python code formatter). hello.py is the target file to format. This command runs Black on your hello.py file to auto-format it according to Black’s style rules.

Using uv tool run:

uv tool run black hello.py

Using the shorter uvx command:

uvx black hello.py

When these commands are run, UV creates a temporary virtual environment in its cache, installs the tool, and runs it from there. This allows you to use command-line tools without installing them in the project’s virtual environment, leading to faster execution and cleaner project dependencies. These cached environments are automatically cleaned up when UV’s cache is cleared and are perfect for occasional use of development tools.

What Are Lock Files in UV?

Lock files (uv.lock) are an important part of dependency management in UV. Each time you run an UV add command, UV creates and/or updates a uv.lock file. The uv.lock file:

• Tracks and records the exact versions of all dependencies and their sub-dependencies.
• Enables reproducible builds by “locking” dependency versions between environments.
• Helps prevent “dependency hell” by keeping consistent versions of packages.
• Allows installations to go faster because UV can use already locked-down versions instead of resolving dependencies again.

UV automatically tracks the lock file, and you should check it into version control to ensure dependency versions are consistent across your development team.

Lock Files vs requirements.txt

Lock files and requirements.txt both deal with dependencies, but they serve different purposes:

The former, Lock files, are an important component of development, as they help establish reproducible builds. requirements.txt files are a bit less complex than lock files and typically only contain direct dependencies, as they are more widely recognized across Python tools and could serve as a method of sharing/deploying code with the end-user that does not use UV. You can maintain both by using the UV lock file for development, and, when it comes time to deploy, generating a requirements.txt like so:

uv export -o requirements.txt

Advanced Dependency Management With UV

UV provides sophisticated methods for managing dependencies:

Updating Dependencies

The add command can be used to update, change constraints, or specify exact versions of existing dependencies:

Installing the latest version:

uv add requests

Installing a specific version:

uv add requests=2.1.2

Changing constraint bounds:

uv add 'requests<3.0.0'

Making a dependency platform-specific:

uv add 'requests; sys_platform="linux"'

Adding Optional Dependencies

Optional dependencies are packages not required for core functionality but needed for specific features (e.g., Pandas’ excel or plot extras).

First, install the core package:

uv add pandas

Then, add its optional dependencies:

uv add pandas --optional plot excel

These will be listed in your pyproject.toml under [project.optional-dependencies].

Dependency Groups

Dependency groups allow you to organise dependencies (e.g., development, test, and documentation dependencies) to keep production dependencies separate.

To install a new dependency into a particular group, you would use the –group flag:

uv add --group group_name package_name

Users can use –group, –only-group, and –no-group flags to further control which group(s) are installed.

Switching From PIP and Virtualenv to UV

The migration from pip and virtualenv to UV is nearly seamless. This is because UV is built to comply with existing Python packaging standards.

Converting an existing virtualenv project

If you have an existing project:

pip freeze > requirements.txt

Next, you would initiate a new UV project in the same directory:

uv init.

Now you can install your dependencies from the requirements file:

uv pip install -r requirements.txt

Replacing common pip/virtualenv commands

Here is a quick reference for replacing common pip/virtualenv commands:

After you have migrated, you can safely delete your old virtualenv directory. If you find you need to fall back to traditional pip commands, you can always make use of the pip compatibility layer built into UV.

Conclusion

UV stands out from the lot of Python package managers, offering a modern, fast, and effective alternative for managing packages compared to previously established tools. The main advantages of UV include:

• Incredible performance (10-100x faster than pip).
• Compatibility with current Python packaging standards.
• Built-in virtual environment support.
• Extremely efficient dependency resolution and lock-file support.
• Small memory footprint and resource consumption.

Whether you start a brand new project or upgrade an existing one, UV is a solid solution that can improve your Python development workflow. And since it is compatible with existing tools and processes, it is a simple decision for developers who want to take their development toolchain into the 21st century without disrupting their workflows.

As developers, we live in a continuously evolving environment. Tools like UV are examples of how modern languages like Rust can improve developer experience. All while retaining the ease and accessibility that Python developers depend upon.

So now that you know of the clear advantages UV offers as a Python package manager, give it a try for your next project. Make sure to check out the official GitHub repo for current updates or contributions. Also, share your experiences with the development community to help expand the adoption and future enhancements of UV.