alpha

UV

Quick reference for UV package manager commands

#python#uv#packaging

Using uv as Python Package Manager

Python has a long history of package managers, each generation having its own strengths and more importntly, weaknesses. As of 2025, uv is aiming to be the best tool on the market and generally it is. Astral focused on speed which never was a major concern for Python package managers before, but after using uv, going back to pip or poetry feels like a clear downgrade.

uv is available for all major platforms (Linux, macOS). It self-contained, meaning it does not require Python to be pre-installed, it can manage Python distributions itself, downloading and installing specific versions as needed.

# macOS
brew install uv

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

# Docker
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

Bootstrapping a Python Project with uv

Use uv init --package for new projects. This creates a src layout which separates source code from project root, preventing import conflicts and ensuring installed package matches development structure.

uv init --package
uv venv --python 3.13

Generated structure:

  • pyproject.toml - project metadata and dependencies
  • src/<project>/ - package directory with __init__.py
  • .python-version - pins Python version
  • .venv/ - virtual environment

Pin Python to a specific minor version. Prevents unexpected breakage from minor version upgrades across environments.

requires-python = ">=3.13,<3.14"

Use uv add for dependency management. Tracks dependencies in pyproject.toml and updates lockfile automatically. Prefer over uv pip install for project dependencies.

uv add pandas openpyxl           # runtime dependencies
uv add --dev ruff pytest         # dev dependencies

Exclude generated artifacts from version control. Standard .gitignore for Python projects:

.venv/
__pycache__/
*.pyc
*.egg-info/
dist/
build/
.eggs/
.pytest_cache/
.ruff_cache/
.coverage

See Makefile for standard make test, make lint, make fmt targets.

Using uv for Managing Python Virtual Environments

uv can create and manage virtual environments. It handles dependency resolution, installation, and environment setup.

# Create .venv (replaces python -m venv .venv)
uv venv
uv venv --python 3.12

# Install package (replaces pip install <package>)
uv pip install requests

# Run command within venv (replaces source .venv/bin/activate && python main.py)
uv run python main.py
uv run pytest

uv has several notable environment variables to control its behavior:

UV_PYTHON_PREFERENCE=only-system   # Use only system Python (useful in Docker)

References