# pyenv — Manage Python Versions > Practical guide to pyenv – install multiple Python versions side by side, switch per shell or project and build them from source when needed. Source: https://www.jpkc.com/db/en/cheatsheets/package-managers/pyenv/ 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 ` — Install a Python version. ```bash pyenv install 3.12.2 ``` `pyenv install --list` — List all available versions for installation. ```bash pyenv install --list ``` `pyenv install --list | grep '^ *3\.'` — List available CPython 3.x versions. ```bash pyenv install --list | grep '^ *3\.' ``` `pyenv versions` — List all installed versions (marks active one with *). ```bash pyenv versions ``` `pyenv uninstall ` — Uninstall a Python version. ```bash pyenv uninstall 3.11.0 ``` ## Switch Versions `pyenv global ` — Set the global default Python version. ```bash pyenv global 3.12.2 ``` `pyenv global ` — Set multiple global versions (first is default, others as fallback). ```bash pyenv global 3.12.2 3.11.8 ``` `pyenv local ` — Set the Python version for the current directory (creates .python-version). ```bash pyenv local 3.11.8 ``` `pyenv shell ` — Set the Python version for the current shell session only. ```bash pyenv shell 3.10.13 ``` `pyenv shell --unset` — Unset the shell-level version override. ```bash pyenv shell --unset ``` `pyenv version` — Show the currently active Python version and how it was set. ```bash pyenv version ``` ## Info & Commands `pyenv which ` — Show the full path of a command for the active version. ```bash pyenv which python ``` `pyenv whence ` — List versions that provide a specific command. ```bash pyenv whence pip ``` `pyenv commands` — List all available pyenv commands. ```bash pyenv commands ``` `pyenv root` — Show the pyenv root directory. ```bash pyenv root ``` `pyenv prefix ` — Show the install path for a specific version. ```bash pyenv prefix 3.12.2 ``` ## pyenv-virtualenv `pyenv virtualenv ` — Create a virtual environment with a specific Python version. ```bash pyenv virtualenv 3.12.2 myproject-env ``` `pyenv virtualenvs` — List all virtual environments. ```bash pyenv virtualenvs ``` `pyenv activate ` — Activate a virtual environment. ```bash pyenv activate myproject-env ``` `pyenv deactivate` — Deactivate the current virtual environment. ```bash pyenv deactivate ``` `pyenv local ` — Auto-activate a virtualenv when entering a directory. ```bash pyenv local myproject-env ``` `pyenv virtualenv-delete ` — Delete a virtual environment. ```bash pyenv virtualenv-delete myproject-env ``` ## Maintenance `pyenv rehash` — Rebuild shim binaries (run after installing packages with executables). ```bash pyenv rehash ``` `pyenv update` — Update pyenv and all installed plugins (via pyenv-update plugin). ```bash pyenv update ``` `pyenv doctor` — Check pyenv installation for potential issues. ```bash 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. ## Further Reading - [pyenv – GitHub project](https://github.com/pyenv/pyenv) – source code, installation and the full command reference - [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) – plugin for managing virtual environments around pyenv - [Suggested build environment](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) – list of required build dependencies per operating system ## Related Commands - [apk](https://www.jpkc.com/db/en/cheatsheets/package-managers/apk/) – package manager for Alpine Linux - [apt](https://www.jpkc.com/db/en/cheatsheets/package-managers/apt/) – high-level package manager for Debian and Ubuntu - [apt-get](https://www.jpkc.com/db/en/cheatsheets/package-managers/apt-get/) – classic package manager for Debian systems