pyenv

List all available commands

$ pyenv commands

$ pyenv versions

$ pyenv install --list

$ pyenv install [2.7.10]

$ pyenv uninstall [2.7.10]

$ pyenv global [2.7.10]

$ pyenv local [2.7.10]

pyenv <command> [arguments...]

install <version>
    Installs a specific Python version (e.g., 3.9.7).

uninstall <version>
    Uninstalls a previously installed Python version.

global <version>
    Sets the global Python version to be used by default across all shells.

local <version>
    Sets a project-specific Python version, usually by creating a .python-version file in the current directory.

shell <version>
    Sets a session-specific Python version, active only for the current shell session.

versions
    Lists all installed Python versions and indicates the currently active one.

which <command>
    Displays the full path to an executable (e.g., python, pip) managed by pyenv.

rehash
    Rebuilds pyenv shims to ensure that newly installed executables are found.

virtualenv <python_version> <env_name>
    Creates a virtual environment using a specific Python version (requires pyenv-virtualenv plugin).

activate <env_name>
    Activates a pyenv managed virtual environment (requires pyenv-virtualenv plugin).

deactivate
    Deactivates an active pyenv managed virtual environment.

update
    Updates pyenv and its plugins (requires pyenv-update plugin).

help [command]
    Displays helpful information about pyenv or a specific subcommand.

pyenv is a simple, yet powerful command-line tool that allows you to manage multiple Python versions on a single machine. It enables seamless switching between different Python interpreters (e.g., Python 2.7, 3.8, 3.9) for various projects without interfering with your system Python or other applications.

Unlike other version managers, pyenv operates by modifying your PATH environment variable and utilizing a concept called "shims," rather than relying on sudo or directly altering system files. This design ensures that pyenv works on a per-user basis, providing an isolated and consistent environment for development. It also integrates well with virtualenv and conda through plugins, extending its utility to manage project-specific dependencies. Its primary benefit lies in preventing dependency conflicts, facilitating testing across different Python versions, and maintaining a clean development setup for Python applications.

• pyenv manages Python versions, not Python packages. For package management, you still need pip or conda.
• Requires specific PATH setup and shell initialization scripts (e.g., ~/.bashrc, ~/.zshrc) to function correctly.
• Python versions installed by pyenv are built from source, which might require development tools and libraries to be present on your system.
• Does not manage system-wide Python installations or packages that rely on them.

To use pyenv, it typically needs to be cloned from its GitHub repository, added to your shell's PATH, and then initialized in your shell's configuration file (e.g., .bashrc, .zshrc). This setup ensures that pyenv's shims directory is prepended to your PATH, allowing it to intercept python and pip commands.

pyenv does not alter your system Python. Instead, it works by placing shims (small executable files) in your PATH that intercept calls to python, pip, and other Python-related executables. When you run python, pyenv's shim takes over, determines which Python version is active (based on global, local, or shell settings), and then transparently redirects the call to the correct Python interpreter installed by pyenv. The pyenv rehash command is crucial as it rebuilds these shims after new Python versions or packages with executables are installed.

pyenv's functionality can be greatly extended through its plugin system. Key plugins include pyenv-virtualenv for seamless integration with Python virtual environments, pyenv-update for easy updates of pyenv itself, and pyenv-doctor for checking build dependencies. These plugins are usually installed alongside pyenv or separately from their respective GitHub repositories.

pyenv was created by Yamashita, inspired by rvm (Ruby Version Manager) and nvm (Node Version Manager). It filled a significant gap in the Python ecosystem for managing multiple interpreters in a user-friendly and non-invasive way. Its initial releases focused on the core functionality of installing and switching Python versions.

Over time, its modular design allowed for a rich plugin ecosystem, notably pyenv-virtualenv (for virtual environment management) and pyenv-update (for easier self-updates), which have become essential components of the pyenv experience. It has gained widespread adoption in the Python community due to its reliability and flexibility.

virtualenv(1), pip(1), python(1), nvm(1), rvm(1)