uv: Faster Package and Environment Management

Introduction

In this chapter, you will learn uv, a modern and fast Python package/environment management tool. uv can handle virtual environments, dependency installation, and lockfile-based reproducibility with excellent performance. Once you understand uv, your daily Python workflow can become cleaner and much faster.

Prerequisites

  • Python 3.10+ installed
  • Basic understanding of pip, virtual environments, and requirements.txt
  • Ability to run terminal commands

What Is uv

uv is a high-performance Python toolchain manager (built in Rust) focused on:

  • dependency management
  • virtual environment management
  • reproducible project setup
  • fast install and resolution

Compared with traditional pip + venv flows, uv often feels significantly faster.

1) Install and Check uv

Install uv (example command may vary by platform):

bash
pip install uv

Check version:

bash
uv --version

If uv is not found, restart terminal or ensure script path is in PATH.

2) Create a Project with uv

Initialize project:

bash
uv init my_project
cd my_project

This creates a modern Python project structure with dependency metadata.

3) Add and Remove Dependencies

Add dependency:

bash
uv add requests

Add specific version:

bash
uv add "requests==2.32.3"

Remove dependency:

bash
uv remove requests

uv updates dependency records and lock data automatically.

Tip

Best Practice

Prefer uv add ... over manual text editing for dependency files to keep metadata consistent.

4) Sync Environment

Use uv sync to align environment with project dependency definitions.

bash
uv sync

This is similar to "install exactly what project declares."

Very useful for:

  • onboarding teammates
  • CI reproducibility
  • switching machines

5) Run Commands with uv

Run Python commands in the project environment:

bash
uv run python main.py

Run tools:

bash
uv run pytest
uv run ruff check .

This avoids activation confusion in many workflows.

6) uv vs pip (Beginner View)

  • Speed: uv is usually faster
  • Workflow: uv integrates dependency + environment flow
  • Compatibility: pip remains universal and widely documented

You can still use pip when needed, but uv offers a more integrated developer experience.

7) Real Mini Example: Quick API Project Setup

Goal: create and run a tiny script with requests via uv.

Step 1: initialize

bash
uv init api_demo
cd api_demo

Step 2: add dependency

bash
uv add requests

Step 3: create main.py

python
import requests
 
response = requests.get("https://api.github.com", timeout=10)
print("Status:", response.status_code)

Step 4: run

bash
uv run python main.py

This demonstrates a full modern dependency workflow in a few commands.

Warning

Do not mix too many package managers in one project without clear rules.
Pick one primary workflow (uv or pip-centric) to avoid lockfile/environment confusion.

Common Beginner Mistakes

Mistake 1: Running Commands Outside Project Root

uv metadata files are project-scoped; running in wrong directory causes confusion.

Mistake 2: Editing Dependency Metadata Manually

Manual edits can desync lock/state. Use uv add/remove/sync instead.

Mistake 3: Assuming Global Environment Is Updated

uv focuses on project-local reproducible environments, not random global installs.

Surprise Practice Challenge

Build a "UV Setup Drill":

  1. Initialize a new project with uv
  2. Add requests and python-dateutil
  3. Write one script using both packages
  4. Run script with uv run
  5. Clone project to another folder and recover environment with uv sync

If you finish this, you already have practical modern Python environment management skills.

FAQ

Should I replace pip completely with uv?

Not required. You can adopt uv gradually, especially for new projects.

Is uv good for teams?

Yes. Lock/sync workflows improve reproducibility and reduce environment drift.

Can I still use virtual environments with uv?

Yes. uv manages project environments as part of its workflow.

When should beginners use uv?

If you are starting new projects and want a modern, fast workflow, this is a great time to begin.