PROVIDER - Lightweight Python version management

pyenv

pyenv manages several Python versions through shell functions with 3 scopes - global, directory and session - and switches automatically from .python-version; pairing with pyenv-virtualenv covers environments too, though source builds are slow and Windows needs an alternative.

Developer Tools United States 2026.11.19
4.1pts

Detailed Notes

Pros 5 items

Manages several Python versions through shell functions, covering 3.x branches and legacy 2.x releases
Offers 3 scopes for version selection: global, directory and shell session
Reads 1 .python-version file per project so the declared version applies automatically
Works with 20+ plugins such as pyenv-virtualenv to manage versions and environments together
Allows custom compile flags for 2 build goals: optimisations or debug symbols

Cons 4 items

Building from source is slow, with a single version sometimes taking several minutes
Compilation needs system development libraries, so missing headers break installs
Native Windows is unsupported and requires pyenv-win
It does not install dependencies, so pip or poetry is still required

Service Overview

pyenv is the most common version manager in the Python ecosystem. It rewrites PATH through shell functions, keeping several Python versions on one machine and choosing among them by directory or session.

In the development tools category it is the single-language version layer: lighter than conda and closer to the official CPython build flow, which suits teams that need precise interpreter control.

Key Strengths

  • Full version range: covers 3.x branches and legacy 2.x
  • Three scopes: global, directory and session granularity
  • Directory convention: .python-version applies automatically
  • Plugin ecosystem: pyenv-virtualenv and similar extend it
  • Build control: compile flags can be customised

Product Ecosystem

Platform capabilities

Version install and switch, version listing, directory configuration, custom compile flags, virtualenv plugins and mirror configuration.

Integrations

Works with pyenv-virtualenv, pip, poetry, tox, GitHub Actions and mainstream editors.

Typical scenarios

Maintaining projects on multiple Python versions, preparing scientific environments and reproducing issues on older versions.

Limitations

  • Build time: source installs can take minutes per version
  • System dependencies: missing development headers break installs
  • Windows gap: pyenv-win and similar are required
  • No package management: pip or poetry still installs dependencies

Use Cases

  • Several Python versions side by side (★★★★★): the core scenario
  • Precise interpreter control (★★★★☆): compile flags adjustable as needed
  • Data science environments (★★★☆☆): conda eases binary dependencies
  • Windows development (★★★☆☆): use pyenv-win instead

Pricing

Item Price Notes
pyenv itself $0 MIT open source, commercial use allowed
Python versions $0 Official sources are free
Commercial support None GitHub issues only

FAQ

Should I choose pyenv or conda?

Choose pyenv for precise CPython version control and conda when many binary scientific dependencies are involved.

Why does compiling a version fail?

Usually missing openssl or readline development libraries; install the matching system packages and retry.

Does it conflict with the system Python?

No, pyenv forwards through shims and leaves the system Python untouched.

How does it work with virtual environments?

With the pyenv-virtualenv plugin you can create isolated environments per Python version.

Code Examples

# Install pyenv on macOS
brew install pyenv

# Install and inspect versions
pyenv install 3.11.8
pyenv versions

# Set global and project versions
pyenv global 3.11.8
cd my-project && pyenv local 3.11.7

# Temporary session switch
pyenv shell 3.12.2

Community & Resources

Visit pyenv Website → https://github.com/pyenv/pyenv
Visit Website ↗