uv.md

UV Cheatsheet

UV is a Python package manager and project tool. This cheatsheet covers installation, project management, dependency handling, and more.

Table of Contents

• Installation
• Basic Commands
• Project Initialization
• Managing Dependencies
• Running Code
• Python Version Management
• Tools Management
• Building and Publishing
• Workspaces
• UV Pip Compatibility
• Inspecting Project Structure
• Managing UV State

Installation

Linux & macOS

curl -LsSf https://astral.sh/uv/install.sh | sudo sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew (macOS)

brew install uv

Basic Commands

Check Installed Version

uv version

Get Help

Note: Check if these commands produce different results

uv help
uv --help

Enable Shell Autocompletion

Add to .zshrc (for Zsh) or equivalent for Bash to enable on startup

eval "$(uv generate-shell-completion zsh)"

Project Initialization

Create a New Project

uv init project-name     # Basic project
uv init --bare example   # Minimal project

Creating a Workspace Project

Creates a project that can contain other projects

uv init --workspace my-workspace

Create a Package Application

Default build system is Hatchling; override with --build-backend

uv init --package example-pkg
uv init --package example-pkg --build-backend hatchling/setuptools/maturin/flit-core/scikit-build-core

Create a Library

uv init --lib example-lib

Projects with Extension Modules

Rust

uv init --build-backend maturin example-ext

C, C++, Fortran, Cython

uv init --build-backend scikit-build-core example-ext

Managing Dependencies

Add Dependencies

uv add litellm langchain   # Multiple packages
uv add -r requirements.txt  # From file
uv add requests             # Latest version
uv add requests=2.1.2       # Specific version
uv add 'requests<3.0.0'     # Version bounds
uv add 'requests; sys_platform="linux"'  # Platform-specific

Add Optional Dependencies

Install core package first, then add optional features

uv add pandas
uv add pandas --optional plot excel

Add Dependency Groups

uv add --group group_name package_name

Remove Dependencies

uv remove scikit-learn

Export to requirements.txt

uv export -o requirements.txt
uv export -o requirements.txt --no-hashes # without hashes

Sync Dependencies

Aligns environment with project dependencies

uv sync

Lock Dependencies

Creates a lockfile (automatic on project creation)

uv lock

View Dependency Tree

uv tree

Running Code

Run Python Commands

uv run python -c "import example"

Run Python Scripts

uv run hello.py

Run Bash Scripts

uv run bash scripts/foo.sh

Run a Package

uv run --directory example-pkg example-pkg

Python Version Management

List Installed Python Versions

uv python list --only-installed

Change Python Version

Update .python-version file, then sync environment:

uv sync

Install dependencies:

uv pip install -e .

Fix Permission Denied Errors (macOS/Linux)

sudo chown -R $USER ~/.local/share/uv

Tools Management

Run Tools

Temporarily run tools like black, flake8, pytest, mypy, etc.

Full command:

uv tool run black hello.py

Short alias (uvx):

uvx black hello.py
uvx ruff check .
uvx pytest

Install Tools User-Wide

uv tool install black ruff mypy pytest

Uninstall Tools

uv tool uninstall

List Installed Tools

uv tool list

Update Shell for Tools

Add tool executables to PATH

uv tool update-shell

Building and Publishing

Build Package

uv build

Publish Package

uv publish

Workspaces

Share dependencies and Python versions across projects

Sub-projects are automatically added to the workspace

To exclude a project from the workspace:

uv init another_project --no-workspace

To create a workspace project:

uv init --workspace my-workspace

UV Pip Compatibility

UV supports pip commands as drop-in replacements

uv pip install -r requirements.txt
uv pip list
uv pip freeze

Inspecting Project Structure

Not UV-specific; requires tree command

tree example-app

Managing UV State

Cache Management

uv cache clean    # Clear cache
uv cache prune    # Remove outdated cache
uv cache dir      # Show cache directory

Directory Paths

uv tool dir       # Tool directory
uv python dir     # Python versions directory

Update UV

uv self update