Python Development Environment Setup

Set up a complete, reproducible Python development environment using devenv, uv, ruff, and basedpyright.

Tools Included

Prerequisites

• •Nix package manager installed
• •direnv installed and hooked into shell
• •devenv CLI installed

Command Options

Generated Files Overview

Implementation Steps

1. Create devenv.yaml

Define Nix inputs and cachix caches. See examples/devenv.yaml for complete template.

2. Create devenv.nix

Configure Python version, packages, pre-commit hooks, and shell initialization.

Key sections:

• •languages.python - Python version and uv configuration
• •packages - Development tools (ruff, basedpyright, treefmt)
• •git-hooks.hooks - Automated linting on commit
• •enterShell - Welcome message with available commands

For database support, add packages and environment variables. See references/database-variants.md.

3. Create .envrc

#!/usr/bin/env bash
export DIRENV_WARN_TIMEOUT=20s
eval "$(devenv direnvrc)"
use devenv

4. Create pyproject.toml

Configure project metadata, dependencies, and tool settings:

• •[project] - Name, version, Python requirement
• •[tool.ruff] - Linting rules and formatting
• •[tool.mypy] - Type checking configuration
• •[tool.pytest] - Test configuration

For framework-specific settings, see references/framework-variants.md.

5. Create pyrightconfig.json

Configure type checker with appropriate strictness level:

• •typeCheckingMode: "standard" (default) or "strict"
• •Exclude common directories (migrations, pycache, .venv)

6. Create treefmt.toml

Configure formatters for Python (ruff) and Nix (nixfmt).

7. Create .claude/.lsp.json (unless --no-lsp)

Enable Claude Code LSP integration with basedpyright.

8. Update .gitignore

Add exclusions for development artifacts, virtual environments, and tool caches.

Setup Commands

After generating files:

# Create source directory structure (required for hatchling)
mkdir -p src/my_project
touch src/my_project/__init__.py

# Enter the environment (auto-creates lock file)
direnv allow

# Install Python dependencies
uv sync

# Verify setup
python --version
ruff --version
basedpyright --version

Verification

# Check devenv status
devenv info

# Run type check
basedpyright

# Run linter
ruff check .

# Check formatting
ruff format --check .
treefmt --check

Troubleshooting

direnv not loading

Ensure direnv is hooked into shell:

# For bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# For zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# Then allow the directory
direnv allow

basedpyright not finding packages

Ensure virtual environment exists and packages are installed:

uv sync

Database compilation errors

See references/database-variants.md for required environment variables.

Additional Resources

Reference Files

• •references/database-variants.md - MySQL and PostgreSQL configuration details
• •references/framework-variants.md - Django and FastAPI specific settings

Example Files

Complete, working configuration templates in examples/:

• •devenv.yaml - Nix inputs configuration
• •devenv.nix - Base development environment
• •pyproject.toml - Project and tool configuration
• •pyrightconfig.json - Type checker settings
• •treefmt.toml - Formatter configuration
• •lsp.json - Claude Code LSP config
• •gitignore - Git exclusions