uv

uv is a modern tool for managing Python project environments and packages quickly and efficiently.

It combines virtual environment management, traditionally handled with venv, and package management, traditionally handled with pip. Its main advantages are ease of use and very fast performance.

If you are familiar with Node.js, you can think of uv as managing Python environments in a way similar to npm, the package manager commonly used with Node.js.

Key Features

Fast creation and management of virtual environments.
Efficient and fast package installation and dependency management.
Easy management and reproduction of project dependencies with simple commands.

Core Concepts

Virtual environment: An isolated Python environment for each project that prevents package conflicts.
pyproject.toml: A standard file that defines project metadata and dependencies.
uv.lock: A lock file that records the exact versions and hashes of all installed packages so that the same environment can be reproduced elsewhere.

Usage Examples

1. Starting a new project

Initialize a project directory as a Python project.

Example: a project directory named my_project/

# Create a directory
mkdir my_project

# Move into the directory
cd my_project

# Initialize the project
uv init

This creates several files, including pyproject.toml.

Suppose, for example, that the project requires NumPy.

Example: main.py

import numpy as np

print(np.array([1, 3]).mean())

Install the package using the uv add command:

# Add the numpy package
uv add numpy

If it does not already exist, uv creates a .venv directory and sets up the virtual environment there.

To run code inside this virtual environment, use uv run:

# Run `main.py` in the current virtual environment
uv run python main.py

# Or
uv run main.py

Packages added to the project become project dependencies. These dependencies should be recorded in a lock file. This process is called locking dependencies.

# Lock dependencies
uv lock

You can then see that a uv.lock file has been created.

2. Starting from an existing project

This is the typical case when joining an existing Python project.

Example: a project directory named your_project/

# Move into the directory
cd your_project

To reproduce the same environment, install the dependencies recorded by the project. If a uv.lock file is present, uv uses it when synchronizing the environment with the uv sync command.

# Install dependencies
uv sync --locked

As before, if .venv does not already exist, uv creates it as the project’s virtual environment. You can then use uv run:

# Run in the current environment
uv run python main.py

# Or
uv run main.py

3. Summary

For a new project

# Create a directory
mkdir my_project

# Move into the directory
cd my_project

# Initialize uv
uv init

# Add a package
uv add numpy

# Run in the current environment
uv run main.py

# Lock dependencies
uv lock

For an existing project

# Move into the directory
cd your_project

# Install dependencies
uv sync

# Run in the current environment
uv run main.py