Links

uv

Description

unified tool
- package installer, replaces pip, pip-tool, pipx
- environment manager, replace venv
- Python version manager
- project manager, replaces poetry
very fast: written in Rust

CLI

uv --version

New project

uv init [project]
uv init  # from the [project] folder if it already exists
uv init --lib [lib]  # for a lib
# create .gitignore, .python-version, main.py, pyproject.toml and README.md
uv init [project] --python 3.10  # for a specific version of python

Packages management

uv add [package]  # add a new package
# create the venv if needed
# update the pyproject.toml and uv.lock
# --package [package]  add a dependency to a specific sub-package of your project

uv sync  # add / remove packages regarding the pyproject.toml

uv tree  # display the tree dependencies
uv tree --package package1  # display the tree dependencies of package1
uv tree --package package1 --reverse  # display the tree reverse-dependencies of package1

Optional group dependencies

uv add --dev pytest

uv sync --group dev
uv sync --all-extra

Cache

Packages and wheels are stored in a cache.

# remove unused items
uv cache prune

# clear the cache
uv cache clean

Lock

# update all the dependencies in the uv.lock file
uv lock --upgrade --dry-run

uv lock --upgrade-package <my_package>

uy sync  # apply the updates

Local and editable dependencies

uv add --editable ./packages/my-package/

pyproject.toml

dependencies = [
    "my-package"
]

[tool.uv.source]
my-package = { woarkspace = true, editable = true }

[tool.uv.workspace]
members = [
    "packages/my-project"
]

Python versions

# list all python versions available on your system
uv python list

# install locally a specific python version
uv python install 3.15

Run

uv run .\main.py
# create the venv
# fetch the dependencies
# run the main.py

# interactive session
uv run --with ipython python

pyproject.toml

[project]
name = "My Project"
version = "0.1.0"
description = "Project description"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "ruff>=0.14.11"
]

[project.scripts]
key = my_project.module1:function1
# allow to use: "uv run key" to call my_project.module1:function1

# to build the package
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Development tools

Tool type	Description	Tools
Linter	catch bugs and style issues	ruff
Formatter	ensure consistent code style	ruff
Type checker	validate type annotation	mypy

uv run ruff check
uv run ruff format .\path\

uv run mypy .\path\

# installation to an isolated env accessible from everywhere
uv tool install ruff
uv tool install mypy
# list
uv tool list
# upgrade
uv tool upgrade ruff

# installation per projet
uv add --dev ruff mypy

pyproject.toml

# format rules
[tool.ruff.format]
docstring-code-format = true

Poe the poet

For scripting and task automation.

pyproject.toml

# format rules
[tool.poe.task]
format = "ruff format ./src/ --check"
lint = "ruff check ./src/"
checks = ["format", "lint"]
_private = "not callable command"
watch = "watchfiles --filter python 'poe checks' src"

[tool.poe.tasks.task1]
parallel = ["_task2", "_task3"]

# call the format task
poe format

# installation
uv tool install poethepoet
uv tool install watchfiles

Wheel

# create a wheel in the dist folder
uv build .\packages\package1\ --wheel

pyproject.toml

[build-system]
requires = ["uv_build"]
build-backend = "uv_build"