🐍 Python Development Environment Architecture

System Level (CachyOS/Arch)

📦 System Python (/usr/bin/python)

🔧 python-pip

Only for system tools and bootstrapping. Don't install packages here!

↓

Python Version Management (pyenv)

🐍 Python 3.12.11

🐍 Python 3.11.9

🐍 Python 3.10.x

🐍 Python 3.13.x

Isolated Python versions in ~/.pyenv/versions/

Switch versions: pyenv global/local/shell

↓ branches to ↓

Global CLI Tools (pipx)

📊 ipython

🎨 black

⚡ ruff

📓 jupyter

🚀 uv

Each tool in its own isolated venv (~/.local/pipx/venvs/)

No dependency conflicts!

Project Environments

Option A: uv (recommended)

📁 project1/.venv

📁 project2/.venv

Option B: pip + venv

📁 project3/venv

Project-specific dependencies, fully isolated

🔑 Key Concepts:
• System Python: Bootstrap only, leave untouched
• pyenv: Manages multiple Python versions
• pipx: Installs CLI tools globally, each in isolation
• pip: Used inside virtual environments for project deps
• uv: Fast alternative to pip+venv (10-100x faster)

📋 Workflow:
1. Use pyenv to set Python version for project
2. Use uv/venv to create isolated environment
3. Use pip/uv to install packages in that environment
4. Use pipx for tools you want available everywhere (black, ruff, etc.)