What is pyenv and How to Install It?

What is pyenv?

Short answer: pyenv is a tool that installs several Python versions on the same computer and lets you switch between them with one command. Each project can use its own version, and the Python that came with your system stays untouched.

pyenv install 3.15.2        # install a version
pyenv global 3.15.2         # default for your user
cd old-app && pyenv local 3.14.10   # this folder uses 3.14
python --version            # Python 3.14.10

pyenv works on macOS and Linux. On Windows you use pyenv-win, a separate project with the same commands. At the time of writing, the latest releases are pyenv 2.8.14, pyenv-win 3.1.1 and Python 3.15.2.

pyenv install downloads a version, pyenv global makes it your default and pyenv local pins a different one for a single project.

pyenv commands at a glance

What is pyenv used for?

• Different projects, different versions. An old app may need Python 3.12 while a new one uses 3.15. pyenv switches automatically when you enter each folder.
• Try a new version safely. Install the latest Python next to the one you use, test your code and go back with one command.
• No sudo and no system changes. Every version lives in ~/.pyenv/versions, inside your user folder. macOS and Linux tools that depend on the system Python keep working.
• The same version for the whole team. Commit the .python-version file and everyone with pyenv gets the same Python in that project.

pyenv chooses the version in this order: the PYENV_VERSION variable (set by pyenv shell), a .python-version file in the current folder or a parent folder (set by pyenv local), and finally the global version.

Install pyenv on Mac

1. Install the build tools and libraries. pyenv compiles Python from source, so it needs them first:

xcode-select --install
brew install openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig

2. Install pyenv with Homebrew:

brew update
brew install pyenv

3. Add pyenv to zsh, the default shell on macOS:

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

4. Restart the shell and check it:

exec "$SHELL"
pyenv --version   # pyenv 2.8.14

This works the same on Apple Silicon and Intel Macs.

Install pyenv on Linux

1. Install the build dependencies. On Ubuntu, Debian or Mint:

sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libzstd-dev

2. Run the official installer. It clones pyenv into ~/.pyenv and adds the pyenv update command:

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

If you prefer, clone it yourself with git clone https://github.com/pyenv/pyenv.git ~/.pyenv.

3. Add pyenv to bash:

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

If you have ~/.profile or ~/.bash_profile, add the same three lines there too, changing the file name. With zsh, use ~/.zshrc and pyenv init - zsh, as on Mac.

4. Restart the shell: exec "$SHELL", then check it with pyenv --version.

Install pyenv on Windows with pyenv-win

pyenv itself doesn't run on Windows. Install pyenv-win from PowerShell:

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

Close and reopen PowerShell, then run pyenv --version. The commands are the same as on Mac and Linux: pyenv install, pyenv global and pyenv local. Run pyenv update first so pyenv-win knows the newest Python versions.

If you work in WSL (Ubuntu on Windows), follow the Linux steps inside WSL instead.

Install and switch Python versions

pyenv install --list | grep " 3.15"   # versions you can install
pyenv install 3.15.2
pyenv install 3.14.10
pyenv versions
#   system
#   3.14.10
# * 3.15.2 (set by /home/ana/.pyenv/version)

Set the default version for your user, and a different one for a project:

pyenv global 3.15.2
 
cd old-app
pyenv local 3.14.10        # creates old-app/.python-version
python --version           # Python 3.14.10

When you leave the folder, the global version is back. To go back to the Python that came with your system, run pyenv global system.

pyenv vs venv: use both

They solve different problems:

The usual setup is pyenv to choose the version and venv for the packages:

cd my-app
pyenv local 3.15.2
python -m venv .venv
source .venv/bin/activate
pip install requests

The pyenv-virtualenv plugin can create environments with pyenv virtualenv 3.15.2 my-app, but plain venv is enough for most projects.

Update pyenv

• Installed with Homebrew: brew update && brew upgrade pyenv
• Installed with pyenv.run: pyenv update
• Installed with git: git -C ~/.pyenv pull
• pyenv-win: run the PowerShell installer again, or pyenv update to refresh the list of versions

Update pyenv when pyenv install --list doesn't show a Python version that was just released.

Use AI to set up pyenv

An assistant like ChatGPT, Claude or GitHub Copilot can adapt the setup to your system and read an install error with you. These three prompts are ready to copy.

1. Set up pyenv for your system

I use [macOS on Apple Silicon / Ubuntu 24.04 / Windows 11] with [zsh / bash / PowerShell].
Give me the exact steps to install pyenv, set it up in my shell
and install Python [version]. Explain what each step does.

2. Fix a failed install

pyenv install [version] failed on [your system] with this output:
[paste the last 30 lines]
Explain which dependency is missing and give me the command to fix it.

3. Set up a project

My project needs Python [version] and these packages: [list them].
Show me how to set it up with pyenv local and venv so my team gets the same setup.

Read each command before you run it, especially the ones that use sudo or change your shell files.

Common problems with pyenv

Related guides

• How to install Python
• How to check your Python version
• How to update your Python version
• How to update Python in the terminal
• How to exit Python in the terminal
• How to install pandas in Python