Uv Python Management

Introduction

UV is a modern Python package manager and virtual environment tool that offers significant performance improvements over traditional tools like pip and venv. This guide covers how to effectively use UV for Python project management.

Installation

Linux

# Using the installer script
curl -LsSf https://astral.sh/uv/install.sh | sh

Managing Python Versions

UV can manage Python installations for you. Here's how to work with Python versions:

Installing Python

# Install latest Python version
uv python install

# Install specific Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12

# Install PyPy
uv python install [email protected]

Listing Python Versions

# List available and installed versions
uv python list

# Show all versions including other platforms
uv python list --all-versions

# Only show installed versions
uv python list --only-installed

Finding Python Executables

# Find default Python
uv python find

# Find specific version
uv python find >=3.11

Project Management

UV provides robust project management capabilities through its project system.

Creating a New Project

# Create a new project
uv init my-project
cd my-project

# Or initialize in current directory
mkdir my-project
cd my-project
uv init

This creates:

• pyproject.toml - Project configuration and dependencies
• .python-version - Python version specification
• README.md - Project documentation
• main.py - Initial Python file

Project Structure

my-project/
├── .venv/               # Virtual environment (created on first use)
├── .python-version      # Python version specification
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
├── README.md           # Project documentation
└── main.py             # Main Python file

Managing Dependencies

# Add dependencies
uv add requests
uv add 'flask>=2.0.0'
uv add 'pytest[testing]'

# Remove dependencies
uv remove requests

# Update dependencies
uv lock --upgrade-package requests

# Install all dependencies
uv sync

Virtual Environment Management

UV automatically manages virtual environments for projects and can work with existing environments.

Creating Virtual Environments

# Create venv in default location (.venv)
uv venv

# Create venv with specific name
uv venv my-env

# Create venv with specific Python version
uv venv --python 3.12

Working with Virtual Environments

# Activate virtual environment
# On Unix/macOS:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

# On Fish shell:
source .venv/bin/activate.fish

# Deactivate virtual environment
deactivate

Using Existing Environments

UV automatically detects and uses virtual environments in the following order:

1. Active virtual environment (VIRTUAL_ENV)
2. Active Conda environment (CONDA_PREFIX)
3. .venv in current or parent directories

Package Management

UV provides both high-level project commands and pip-compatible commands for package management.

Project-Based Package Management

# Add package to project
uv add package-name

# Remove package from project
uv remove package-name

# Sync project dependencies
uv sync

# Update lockfile
uv lock

Pip-Compatible Commands

# Install packages
uv pip install package-name
uv pip install -r requirements.txt

# Install in editable mode
uv pip install -e .

# Uninstall packages
uv pip uninstall package-name

# List installed packages
uv pip list

# Show package info
uv pip show package-name

# Generate requirements.txt
uv pip freeze > requirements.txt

Advanced Configuration

pyproject.toml Configuration

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
readme = "README.md"
requires-python = ">=3.8"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "[email protected]" }
]

dependencies = [
    "requests>=2.28.0",
    "flask[async]>=2.0.0",
    "sqlalchemy",
]

[project.optional-dependencies]
test = ["pytest>=7.0", "pytest-cov"]
dev = ["black", "mypy", "ruff"]

[tool.uv]
python-version = "3.12"

UV Configuration Options

[tool.uv]
# Package index configuration
[[tool.uv.index]]
url = "https://pypi.org/simple"
default = true

[[tool.uv.index]]
url = "https://test.pypi.org/simple"
secondary = true

# Build settings
no-binary = ["cryptography", "numpy"]
build-isolation = true

# Cache settings
cache-dir = "~/.cache/uv"

Environment-Specific Settings

[tool.uv.env]
development = { extras = ["dev", "test"] }
production = { extras = [] }

Development Workflows

Local Development Setup

# Initialize new project
uv init my-project
cd my-project

# Set up development environment
uv add --dev black ruff mypy pytest
uv add --dev 'pre-commit>=3.0.0'

# Create pre-commit config
cat > .pre-commit-config.yaml << EOF