Skip to main content

135. System Python Preservation

Status: Accepted Date: 2025-07-06

Context​

Modern Linux distributions, including Ubuntu, rely on a specific version of Python for many core system utilities and scripts (e.g., parts of the package manager, system administration tools). Attempting to uninstall, upgrade, or otherwise modify the system's default Python installation (typically located at /usr/bin/python3) can lead to catastrophic, hard-to-debug failures of the operating system itself.

Decision​

We will adhere to a strict policy of system Python preservation.

Our Ansible automation, specifically the 06_python role, will never touch the system's native Python installation.

This policy is enacted by our decision to use pyenv for all our application-level Python needs (adr://pyenv-version-management). pyenv installs its Python versions in the user's home directory (~/.pyenv), which is completely isolated from the system's directories like /usr/bin.

The system Python is left untouched to perform its role as a core OS dependency. Our development and application Python environments live entirely separate from it, managed by pyenv.

Consequences​

Positive:

  • System Stability: This is the most critical benefit. By not touching the system Python, we guarantee the stability and correct functioning of the underlying operating system. We avoid a huge class of potential, disastrous side effects.
  • Clear Separation of Concerns: Creates a clear and unambiguous separation between "Python, the OS dependency" and "Python, the application runtime". This makes the entire system easier to reason about.
  • No sudo pip: This policy naturally leads to the best practice of never running pip with sudo, as we are never trying to install packages into the system's Python environment. All pip installations happen within a pyenv-managed version or a virtual environment.

Negative:

  • Slightly More Complex Setup: This approach requires the installation and configuration of pyenv, which is slightly more complex than just using the system Python directly.

Mitigation:

  • Essential Complexity: The additional complexity of pyenv is not accidental; it is essential complexity that we adopt to gain the far greater benefits of flexibility, isolation, and system stability. The risk of breaking the OS by meddling with the system Python is unacceptably high, making this trade-off an easy one. The complexity is also fully managed and automated by our Ansible roles.