UV Explained in 5 Minutes The Ultra-Fast Python Package Manager

If you're a Python developer still using pip, it's time for a significant upgrade. Meet UV, a super-fast Python package manager that serves as a powerful replacement for the standard pip install command. With UV, you can install libraries much faster, sometimes achieving up to a 100x performance increase over pip.

But UV's capabilities extend far beyond just installing packages quickly. As this article will demonstrate, UV is a comprehensive tool that can streamline your entire development workflow.

What Can UV Do for You?

  • Scaffold New Projects: Instantly create new Python projects with a boilerplate structure.
  • Generate .gitignore: Automatically add a standard Python .gitignore file.
  • Manage Virtual Environments: Create and manage virtual environments seamlessly.
  • Handle Dependencies: Manage main and development dependencies with ease.

All of this is accomplished with a few simple terminal commands. This guide will provide a quick walkthrough of what UV is, how to set it up, and why you should start using it today.

Getting Started with UV

Setting up UV is straightforward, and you only need to learn a handful of commands to make the most of it.

You can find the specific installation instructions for your operating system on the official documentation. For macOS and Linux, a simple curl command suffices. On Windows, the process is similarly simple. My preferred method on macOS is using Homebrew:

brew install uv

Once installed, verify the installation by running uv --help in your terminal. This command confirms that UV is installed correctly and provides an overview of all available commands, many of which we will cover in this article.

A Modern Python Project Workflow

One of the most significant challenges in Python development has always been the tedious process of starting a new project: creating a repository, setting up a virtual environment, installing requirements, and managing dependencies. UV completely transforms this experience.

Let's walk through creating a new project.

Step 1: Initialize the Project

Open a terminal in your projects directory and run the uv init command:

uv init new-ai-project

This command creates a new folder named new-ai-project populated with essential files.

Step 2: Explore the Project Structure

Navigate into the new directory (cd new-ai-project). You'll find that UV has generated a clean project structure for you:

  • .gitignore: A standard file with common Python excludes.
  • .python-version: A file to pin your project's Python version.
  • hello.py: A simple "Hello, World!" script to test your setup.
  • pyproject.toml: The modern standard for configuring Python projects and their dependencies.
  • README.md: A placeholder for your project's documentation.

Step 3: Add Dependencies

To add dependencies like openai, pydantic, and fastapi, use the uv add command:

uv add openai pydantic fastapi

When you run this, two magical things happen. First, the installation is incredibly fast. Second, UV automatically detects that no virtual environment exists, creates one for you, and installs the packages inside it.

The dependencies are added to your pyproject.toml file, which now serves as the replacement for requirements.txt. The file will look something like this:

[project]
name = "new-ai-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "openai",
    "pydantic",
    "fastapi",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Step 4: Remove Dependencies

Removing packages is just as easy. If you decide you don't need fastapi, simply run:

uv remove fastapi

This command removes the package and updates pyproject.toml. This is a huge improvement over pip, where managing and cleaning up dependencies can be a hassle. UV keeps your dependency list lean, tracking only the libraries you explicitly install, not their sub-dependencies.

Development vs. Production Dependencies

In real-world projects, you need to distinguish between production dependencies and those used for local development and testing. UV handles this elegantly.

To add a development-only dependency, like ipykernel, use the --dev flag:

uv add ipykernel --dev

This adds the package to a separate [project.optional-dependencies] group in your pyproject.toml, creating a clear separation between environments. This practice helps keep your production environment minimal and clean.

Note on Pushing to GitHub

Once your project is set up, you can use the GitHub CLI to quickly create a repository and push your code. This two-step process—using UV to initialize and the GitHub CLI to publish—can take you from an idea to a fully configured GitHub repository in seconds.

gh repo create new-ai-project --private -y && git push -u origin main

Exploring Other Essential UV Commands

UV has several other commands that enhance the development experience. It's worth noting that UV is developed by Astral, the same team behind Ruff, an incredibly fast Python linter that is also highly recommended.

Running Python Files

You can execute Python scripts directly with UV without activating a virtual environment first:

uv run hello.py

Managing Python Versions

UV can even manage your system's Python installations. You don't need a separate tool; you can install and manage multiple Python versions directly through UV. To see which versions are available on your system, run:

uv python list

Syncing Your Environment

When collaborating with a team, uv sync is invaluable. After cloning a repository, a team member can simply run this command:

uv sync

UV will read the pyproject.toml file, create the virtual environment, and install all the necessary dependencies instantly.

Seamless Pip Compatibility

UV is fully compatible with projects that still use requirements.txt. You can use UV to install dependencies from a traditional requirements file without needing to migrate anything.

uv pip install -r requirements.txt

This command will install all the listed packages into the UV-managed virtual environment, making the transition smooth and effortless.

That's a brief overview of what makes UV an exceptional tool for Python developers. For more advanced use cases, such as integration with CI/CD pipelines or Docker, the official documentation is an excellent resource.