Modern Python environment setup using uv.

The problem

Python’s dependency management has historically been messy. Projects need:

1. Isolation — different projects need different package versions
2. Reproducibility — collaborators must get the exact same environment
3. Python version control — projects may require specific Python versions

Traditional tools (pip, venv, requirements.txt) don’t solve all of these well.

Modern solution: uv

uv is a fast Python package manager (written in Rust) that handles virtual environments, dependency resolution, and lockfiles in one tool.

Quick start

uv init              # Initialize project (creates pyproject.toml)
uv add pandas numpy  # Add dependencies
uv sync              # Install everything from lockfile

That’s it. uv automatically:

• Creates .venv/ if it doesn’t exist
• Generates uv.lock with exact versions of all dependencies (including transitive ones)
• Installs everything reproducibly

Avoid mixing with pip or using uv pip — stick to uv add/uv sync to keep pyproject.toml and uv.lock in sync.

Common commands

Project structure

myproject/
├── .python-version   # Python version for this project
├── .venv/            # Virtual environment (gitignored)
├── pyproject.toml    # Project metadata + dependencies
└── uv.lock           # Lockfile (commit this!)

Key files

.python-version

A simple file containing the Python version:

3.12

uv reads this and uses the correct Python version. This file is understood by many tools (pyenv, uv, etc.).

pyproject.toml

The modern standard for Python project configuration (PEP 517, PEP 518). It replaces setup.py, setup.cfg, and requirements.txt.

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "pandas>=2.0",
    "numpy>=1.26",
]

[project.optional-dependencies]
dev = ["pytest", "ruff"]

Why pyproject.toml is better than requirements.txt:

• Standardized — one format for all Python tools
• Structured — metadata, dependencies, and tool configs in one place
• Semantic versioning — specify version ranges, not just exact versions
• Optional dependencies — group dev/test/docs dependencies separately

uv.lock

Auto-generated lockfile with exact versions of all dependencies (including transitive). You want to commit this file — it ensures reproducibility across machines.

Auto-activation with direnv

direnv automatically activates environments when you enter a project directory.

1. Add to ~/.direnvrc:

use_uv() {
    [ -d .venv ] || uv venv
    source .venv/bin/activate
    [ -f uv.lock ] && uv sync
}

2. Create .envrc in your project:

echo "use uv" > .envrc

3. Allow it:

direnv allow

Now when you cd into the project, the environment activates automatically.

Linting and formatting with ruff

ruff is an extremely fast Python linter and formatter (also written in Rust). It replaces flake8, isort, black, and many other tools.

Setup

uv add --dev ruff

Add configuration to pyproject.toml:

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I"]  # E=pycodestyle, F=pyflakes, I=isort

Running manually

ruff check .          # Lint
ruff check --fix .    # Lint and auto-fix
ruff format .         # Format

Format on save (editor integration)

My favorite way to use ruff is setting up “format on save” for my editors so that I don’t even need to think about formatting at all. Once you set up, every file save fixes all the formatting issues automatically.

VS Code: Install the Ruff extension and enable format on save. See VS Code setup docs.

Neovim: Install ruff via Mason, then configure with nvim-lspconfig. See Neovim setup docs.

See also

• uv
• ruff
• direnv