pyenv(1)
pyenv manages multiple Python versions on a single system, allowing you to switch between them per-project or globally.
Synopsis
pyenv <command> [<args>]Description
pyenv is a version manager for Python that lets you install and switch between multiple Python versions without system-wide installation conflicts. It works by inserting a shim directory at the front of your PATH, intercepting Python calls and redirecting them to the appropriate version.
Unlike system package managers, pyenv installs Python versions into your home directory (~/.pyenv/versions), giving you complete control over versions per-project, per-shell session, or globally. It integrates with .python-version files to automatically switch versions when entering a directory.
Common options
| Flag | What it does |
|---|---|
versions | list all installed Python versions; asterisk marks the currently active version |
install | download and compile a Python version; use --list to see available versions |
uninstall | remove an installed Python version from ~/.pyenv/versions |
global | set the global default Python version in ~/.pyenv/version |
local | set the Python version for the current directory via .python-version file |
shell | set the Python version for the current shell session only |
version | show the currently active Python version and how it was set |
which | display the full path to the executable for the active Python version |
rehash | refresh shim directory when new Python versions or executables are added |
-v / --version | display pyenv version number |
Examples
see available Python 3.12.x versions before installation
pyenv install --list | grep '3.12'download, compile, and install Python 3.12.1 into ~/.pyenv/versions
pyenv install 3.12.1list all installed Python versions; the active one is marked with an asterisk
pyenv versionsset Python 3.12.1 as the default version system-wide
pyenv global 3.12.1set Python 3.11.0 for the current directory; creates .python-version file
pyenv local 3.11.0 && cat .python-versionuse Python 3.10.5 for only the current shell session
pyenv shell 3.10.5 && python --versionshow the full path to the currently active python executable
pyenv which pythonremove Python 3.9.0 from the system
pyenv uninstall 3.9.0