pyenv — Manage Python Versions

pyenv is a version manager for Python: it lets you install multiple Python versions side by side and switch between them per shell, per project or globally. A file named .python-version in a project directory pins which version applies there automatically – pyenv achieves this by placing so-called shims on your PATH that forward every call to python, pip and friends to the right version. When needed, pyenv builds the requested versions straight from source, so you're not tied to whatever your distribution ships. This guide walks you through the commands you reach for most – from installing a version to virtual environments with pyenv-virtualenv.

Install & List Versions

pyenv install <version> — Install a Python version.

pyenv install 3.12.2

pyenv install --list — List all available versions for installation.

pyenv install --list

pyenv install --list | grep '^ *3\.' — List available CPython 3.x versions.

pyenv install --list | grep '^ *3\.'

pyenv versions — List all installed versions (marks active one with *).

pyenv versions

pyenv uninstall <version> — Uninstall a Python version.

pyenv uninstall 3.11.0

Switch Versions

pyenv global <version> — Set the global default Python version.

pyenv global 3.12.2

pyenv global <version1> <version2> — Set multiple global versions (first is default, others as fallback).

pyenv global 3.12.2 3.11.8

pyenv local <version> — Set the Python version for the current directory (creates .python-version).

pyenv local 3.11.8

pyenv shell <version> — Set the Python version for the current shell session only.

pyenv shell 3.10.13

pyenv shell --unset — Unset the shell-level version override.

pyenv shell --unset

pyenv version — Show the currently active Python version and how it was set.

pyenv version

Info & Commands

pyenv which <command> — Show the full path of a command for the active version.

pyenv which python

pyenv whence <command> — List versions that provide a specific command.

pyenv whence pip

pyenv commands — List all available pyenv commands.

pyenv commands

pyenv root — Show the pyenv root directory.

pyenv root

pyenv prefix <version> — Show the install path for a specific version.

pyenv prefix 3.12.2

pyenv-virtualenv

pyenv virtualenv <version> <name> — Create a virtual environment with a specific Python version.

pyenv virtualenv 3.12.2 myproject-env

pyenv virtualenvs — List all virtual environments.

pyenv virtualenvs

pyenv activate <name> — Activate a virtual environment.

pyenv activate myproject-env

pyenv deactivate — Deactivate the current virtual environment.

pyenv deactivate

pyenv local <virtualenv-name> — Auto-activate a virtualenv when entering a directory.

pyenv local myproject-env

pyenv virtualenv-delete <name> — Delete a virtual environment.

pyenv virtualenv-delete myproject-env

Maintenance

pyenv rehash — Rebuild shim binaries (run after installing packages with executables).

pyenv rehash

pyenv update — Update pyenv and all installed plugins (via pyenv-update plugin).

pyenv update

pyenv doctor — Check pyenv installation for potential issues.

pyenv doctor

Conclusion

pyenv takes the fight with your system Python off your plate: instead of tinkering with the distribution's own version, you keep as many versions side by side as you like and decide precisely which one each project uses. For this to work, the shell initialization has to be in place – eval "$(pyenv init -)" belongs in your .bashrc or .zshrc, otherwise the shims never kick in. Because pyenv compiles versions from source, you need the right build dependencies up front (such as build-essential, libssl-dev and zlib1g-dev); without them, pyenv install will fail. For isolated project environments, pair pyenv with the pyenv-virtualenv plugin, which cleanly ties virtual environments to a .python-version file.