pyenv — Simple Python Version Management

Introduction

pyenv lets you install and switch between multiple Python versions without touching the system Python. It uses shims and per-directory .python-version files so every project can pin exactly the interpreter it needs.

What pyenv Does

• Installs any CPython, PyPy, Anaconda, or Stackless version from source
• Switches the active Python globally, per-directory, or per-shell session
• Supports .python-version files for automatic per-project switching
• Manages shims in ~/.pyenv/shims so the right binary is always on PATH
• Works alongside virtualenvs via the pyenv-virtualenv plugin

Architecture Overview

pyenv inserts a directory of lightweight shim scripts at the front of your PATH. When you run python, the shim inspects PYENV_VERSION, the local .python-version file, or the global setting to resolve the correct interpreter binary under ~/.pyenv/versions/. Versions are compiled from source using python-build, which ships as a built-in plugin.

Self-Hosting & Configuration

• Install via pyenv-installer one-liner or clone the repo to ~/.pyenv
• Requires common build dependencies (gcc, make, libssl-dev, zlib, etc.)
• Set PYENV_ROOT to relocate the installation directory
• Use pyenv local 3.x.y in a project to create a .python-version file
• Add pyenv-virtualenv plugin for integrated virtualenv management

Key Features

• Zero dependency on system Python — fully self-contained
• Per-directory version switching with automatic detection
• Builds Python from source so any version is available
• Plugin system for virtualenv, pip-rehash, and more
• Shell completion for bash, zsh, and fish

Comparison with Similar Tools

• asdf — universal version manager for many languages but heavier setup for Python-specific needs
• mise — Rust-based polyglot tool manager with TOML config; newer ecosystem
• conda — full environment and package manager oriented toward data science, not just version switching
• uv — ultra-fast package installer that can manage Python versions but focuses on dependency resolution
• deadsnakes PPA — Ubuntu-only; limited to versions the PPA maintainers choose to publish

FAQ

Q: Does pyenv work on macOS and Linux? A: Yes. macOS and most Linux distributions are fully supported. Windows users should use pyenv-win, a separate port.

Q: Can I use pyenv with virtualenvs? A: Yes. The pyenv-virtualenv plugin lets you create, list, and auto-activate virtualenvs tied to specific Python versions.

Q: Does pyenv interfere with system Python? A: No. It only prepends shims to your PATH; the system Python remains untouched.

Q: How do I uninstall a Python version? A: Run pyenv uninstall 3.x.y. The compiled files are removed from ~/.pyenv/versions/.

Sources

• https://github.com/pyenv/pyenv
• https://github.com/pyenv/pyenv/wiki