Skip to main content

134. Pyenv for Python Version Management

Status: Accepted Date: 2025-07-06

Context​

Our projects and development activities require specific versions of Python. The version of Python provided by the operating system's package manager (apt) is often older and is shared across the entire system. Relying on this single, system-wide Python installation is brittle and inflexible. It makes it very difficult to work on multiple projects that have different Python version requirements.

Decision​

We will use pyenv to manage our Python installations.

The 06_python Ansible role is responsible for:

  1. Installing pyenv itself.
  2. Using pyenv to install one or more specific versions of Python (e.g., the latest stable release). The Python versions are compiled from source, ensuring they are cleanly installed and self-contained.
  3. Setting a global default Python version via pyenv global.

This approach treats Python as a piece of user-level tooling, completely separate from the system's own Python (adr://system-python-preservation). It provides a clean, flexible, and powerful way to manage multiple Python environments.

Consequences​

Positive:

  • Version Flexibility: Allows developers to easily install and switch between multiple versions of Python on a per-project or even per-shell basis. This is essential for working in a polyglot environment with diverse project requirements.
  • Isolation: pyenv installs Python versions into a dedicated directory (~/.pyenv), keeping them completely isolated from the system Python. This prevents version conflicts and protects the stability of the host OS.
  • Clean Environment: Provides a clean, known starting point for Python projects, free from any system-level packages that might be present in the OS's Python installation.

Negative:

  • Slower Provisioning: Compiling Python from source via pyenv is significantly slower than installing a pre-compiled binary via apt.
  • Requires Shell Integration: For pyenv to work correctly, the user's shell configuration (.zshrc, .bashrc, etc.) must be modified to add pyenv to the PATH. This is typically handled by chezmoi but represents an extra setup step.

Mitigation:

  • One-Time Cost: The long compilation time is a one-time cost during the initial server provisioning. The subsequent benefits of version flexibility are well worth this initial investment in time.
  • Automated Shell Integration: The required shell integration is a standard part of our dotfiles setup, which is deployed automatically by chezmoi. This is a solved problem within our ecosystem.