How to use uv

Python

Install, configure and usage of uv a Python package manager

Published

June 13, 2025

1 What is uv?

uv is “An extremely fast Python package and project manager, written in Rust.”¹

I’ve been using uv for some projects and I really notice an improvement in the velocity when I’m installing Python packages in comparison with another tools like pip. For example in the Figure 1 we can see the different in time installing the same package with different packages manager where uv is the fastest.

Figure 1: Installing Trio’s dependencies with a warm cache. Source: https://docs.astral.sh/uv/

2 Installation and configuration

We have different options to install uv go ahead to the documentation Installing uv to find the best option for you project.

3 Usage

3.1 Basic commands

Install specific Python version

uv python install 3.12 3.11

List Python versions installed

uv python list

Run a Python script

uv run script.py

3.2 Start a project

Starting a project will create the following files:

main.py
pyproject.toml
uv.lock
.python-version

Commands:

# Start the project hello-world
uv init hello-world

# Start the project hello-world with Python 3.12
uv init hello-world --python 3.12

# Usage the current folder as a project
uv init

# Execute the project
uv run main.py

3.3 Working with virtual environments

Create a virtual environment (this command will create .venv folder)

uv venv

Installing packages on the .venv

# A package
uv pip install PACKAGE_NAME

# A requirements.txt
uv pip install -r requirements.txt

Activate the virtual environment for Bash and ZSH shell

source .venv/bin/activate

3.4 Dependencies management

Add a public library with specific version

uv add 'request==2.31.0'

Add a library using git repository (could be useful for private repositories)

uv add git.https://github.com/...

Install with requirements.txt and constraints.txt files

uv add -r requirements.txt -c constraints.txt

Remove packages

uv remove requests

3.5 Running servers

Run a flask server

uv run -- flask run -p 3000

Run a quarto server in localhost

uv run -- quarto preview mysite --port PORT --host 0.0.0.0

Render quarto document

uv run -- quarto render mysite

3.6 Using integrations

Using Jupyter Lab²

uv run --with jupyter jupyter lab

Using Docker Images with uv installed ³

docker run --rm -it ghcr.io/astral-sh/uv:debian uv --help