Simple Python Version Management: pyenv

pyenv lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.

This project was forked from rbenv and ruby-build, and modified for Python.

What pyenv does...

• Lets you change the global Python version on a per-user basis.
• Provides support for per-project Python versions.
• Allows you to override the Python version with an environment variable.
• Searches for commands from multiple versions of Python at a time. This may be helpful to test across Python versions with tox.

In contrast with pythonbrew and pythonz, pyenv does not...

• Depend on Python itself. pyenv was made from pure shell scripts. There is no bootstrap problem of Python.
• Need to be loaded into your shell. Instead, pyenv's shim approach works by adding a directory to your PATH.
• Manage virtualenv. Of course, you can create virtualenv yourself, or pyenv-virtualenv to automate the process.

---

Table of Contents

• Installation
  • Getting Pyenv
    • Linux/UNIX
      • Automatic Installer
      • Basic GitHub Checkout
    • MacOS
      • Homebrew in macOS
    • Windows
  • Set up your shell environment for Pyenv
  • Restart your shell
  • Install Python build dependencies
  • Upgrade Notes
• Usage
  • Install additional Python versions
    • Prefix auto-resolution to the latest version
    • Python versions with extended support
  • Switch between Python versions
    • Making multiple versions available
  • Uninstall Python versions
  • Other operations
• Upgrading
  • Upgrading with Homebrew
  • Upgrading with Installer or Git checkout
• Uninstalling pyenv
• Pyenv plugins
• How It Works
  • Understanding PATH
  • Understanding Shims
  • Understanding Python version selection
  • Locating Pyenv-provided Python Installations
• Advanced Configuration
  • Using Pyenv without shims
  • Running nested shells from Python-based programs
  • Environment variables
• Development
  • Contributing
  • Version History
  • License

---

Installation

A. Getting Pyenv

---

Linux/Unix

<details>

The Homebrew option from the MacOS section below would also work if you have Homebrew installed.

1. Automatic installer (Recommended)

curl -fsSL https://pyenv.run | bash

For more details visit our other project: https://github.com/pyenv/pyenv-installer

2. Basic GitHub Checkout

This will get you going with the latest version of Pyenv and make it easy to fork and contribute any changes back upstream.

• Check out Pyenv where you want it installed. A good place to choose is $HOME/.pyenv (but you can install it somewhere else):

  git clone https://github.com/pyenv/pyenv.git ~/.pyenv
  

• Optionally, try to compile a dynamic Bash extension to speed up Pyenv. Don't worry if it fails; Pyenv will still work normally:

  cd ~/.pyenv && src/configure && make -C src
  

</details>

MacOS

<details>

The options from the Linux section above also work but Homebrew is recommended for basic usage.

Homebrew in macOS

1. Update homebrew and install pyenv:

   brew update
   brew install pyenv
   

   If you want to install (and update to) the latest development head of Pyenv rather than the latest release, instead run:

   brew install pyenv --head
   

2. Then follow the rest of the post-installation steps, starting with Set up your shell environment for Pyenv.

3. OPTIONAL. To fix brew doctor's warning ""config" scripts exist outside your system or Homebrew directories"

   If you're going to build Homebrew formulae from source that link against Python like Tkinter or NumPy (This is only generally the case if you are a developer of such a formula, or if you have an EOL version of MacOS for which prebuilt bottles are no longer provided and you are using such a formula).

   To avoid them accidentally linking against a Pyenv-provided Python, add the following line into your interactive shell's configuration:

   • Bash/Zsh:

     alias brew='env PATH="${PATH//$(pyenv root)\/shims:/}" brew'
     

   • Fish:

     alias brew="env PATH=(string replace (pyenv root)/shims '' \"\$PATH\") brew"
     

</details>

Windows

<details>

Pyenv does not officially support Windows and does not work in Windows outside the Windows Subsystem for Linux. Moreover, even there, the Pythons it installs are not native Windows versions but rather Linux versions running in a virtual machine -- so you won't get Windows-specific functionality.

If you're in Windows, we recommend using @kirankotari's pyenv-win fork -- which does install native Windows Python versions.

</details>

B. Set up your shell environment for Pyenv

---

The below setup should work for the vast majority of users for common use cases. See Advanced configuration for details and more configuration options.

Bash

<details>

Stock Bash startup files vary widely between distributions in which of them source which, under what circumstances, in what order and what additional configuration they perform. As such, the most reliable way to get Pyenv in all environments is to append Pyenv configuration commands to both .bashrc (for interactive shells) and the profile file that Bash would use (for login shells).

1. First, add the commands to ~/.bashrc by running the following in your terminal:

   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
   echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
   echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc
   

2. Then, if you have ~/.profile, ~/.bash_profile or ~/.bash_login, add the commands there as well. If you have none of these, create a ~/.profile and add the commands there.

   • to add to ~/.profile:

     echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
     echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
     echo 'eval "$(pyenv init - bash)"' >> ~/.profile
     

   • to add to ~/.bash_profile:

     echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
     echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
     echo 'eval "$(pyenv init - bash)"' >> ~/.bash_profile
     

Bash warning: There are some systems where the BASH_ENV variable is configured to point to .bashrc. On such systems, you should almost certainly put the eval "$(pyenv init - bash)" line into .bash_profile, and not into .bashrc. Otherwise, you may observe strange behaviour, such as pyenv getting into an infinite loop. See #264 for details.

</details>

Zsh

<details> Add Pyenv startup commands to `~/.zshrc` by running the following in your terminal:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

If you wish to get Pyenv in noninteractive login shells as well, also add the commands to ~/.zprofile or ~/.zlogin.

</details>

Fish

<details>

1. If you have Fish 3.2.0 or newer, execute this interactively:

   set -Ux PYENV_ROOT $HOME/.pyenv
   test -d $PYENV_ROOT/bin; and fish_add_path $PYENV_ROOT/bin
   

2. Otherwise, execute the snippet below:

   set -Ux PYENV_ROOT $HOME/.pyenv
   test -d $PYENV_ROOT/bin; and set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths
   

3. Now, add this to ~/.config/fish/config.fish:

   pyenv init - fish | source
   

</details>

Nushell

<details>

Add the following lines to your config.nu to add Pyenv and its shims to your PATH. Shell integration (completions and subcommands changing the shell's state) isn't currently supported.

$env.PYENV_ROOT = "~/.pyenv" | path expand
if (( $"($env.PYENV_ROOT)/bin" | path type )