pyenv
Manage multiple Python versions
TLDR
List all available commands
List all Python versions under the ${PYENV_ROOT}/versions directory
List all Python versions that can be installed from upstream
Install a Python version under the ${PYENV_ROOT}/versions directory
Uninstall a Python version under the ${PYENV_ROOT}/versions directory
Set Python version to be used globally in the current machine
Set Python version to be used in the current directory and all directories below it
SYNOPSIS
pyenv
PARAMETERS
commands
List all available pyenv commands.
local
Set or show the local application-specific Python version. If no version is specified, the local version is removed.
global
Set or show the global Python version. If no version is specified, the global version is displayed.
shell
Set or show the shell-specific Python version. If no version is specified, the shell version is displayed.
install
Install a Python version. 'pyenv install --list' displays all available versions.
uninstall
Uninstall a specific Python version.
versions
List all Python versions available to pyenv.
version
Display the currently active Python version and its origin.
version-name
Display the currently active Python version name.
version-file
Display the file from which the current Python version is read.
which
Display the full path to an executable.
rehash
Rehash pyenv shims (refresh the list of available commands).
doctor
Diagnose common problems with pyenv setup.
prefix
Display pyenv's prefix for a specific Python version.
DESCRIPTION
pyenv lets you easily switch between multiple Python versions. It's a simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well. It doesn't require modifying your PATH
permanently until you initialize it and works by intercepting Python commands using shim executables inserted into your PATH
. When you execute a Python command, pyenv determines which Python version to use based on your project, environment variables, and global settings. This allows you to work on different projects requiring different Python versions without interference.
Key features include: Installing multiple Python versions, easy switching between versions, isolated environments for different projects, and integration with virtualenv and other tools. pyenv aims to be a lightweight and flexible solution, avoiding conflicts with system Python installations and other development tools.
CAVEATS
It is important to rehash pyenv after installing new versions of Python or installing packages with executable scripts. Using virtualenv with pyenv is a common pattern and highly recommended for project isolation.
SHELL INTEGRATION
For pyenv to work properly, it needs to be initialized in your shell environment. This typically involves adding a few lines to your .bashrc
, .zshrc
, or equivalent configuration file. These lines ensure that pyenv's shims are added to your PATH
and that the pyenv environment is properly loaded. Check the pyenv documentation for specific instructions for your shell.
UNDERSTANDING SHIMS
pyenv uses 'shims' to intercept calls to Python executables. These shims are lightweight scripts placed in the $(pyenv root)/shims
directory. When you run a command like python
, the shim is executed first. The shim then determines the appropriate Python version to use and forwards the command to the correct Python executable.
HISTORY
pyenv emerged as a response to the challenges of managing multiple Python versions in development environments. Prior to pyenv, developers often relied on system-level installations or manual manipulation of environment variables, leading to conflicts and inconsistencies. pyenv's development focused on providing a lightweight, user-friendly, and non-intrusive solution for version management. It gained popularity as it simplified workflows, reduced conflicts, and allowed developers to easily switch between different Python versions depending on project requirements. The continuous development incorporates bug fixes, feature enhancements, and improvements to compatibility with various Python versions and package management tools.
SEE ALSO
virtualenv(1), python(1)