4Geeks chosen to deliver AI education in the Bahamas alongside Harvard, Oxford, and Columbia.See more
Image: 4geeks logo big
SIGN IN

What is pyenv and How to Install It?

Discover what pyenv is and how to install this powerful tool to manage Python versions on your system. Facilitate project development.
7 min readLast updated

What is pyenv?

Short answer: pyenv is a tool for installing, uninstalling and switching between multiple Python versions on one computer without interfering with the system Python installation. On macOS, install it with brew install pyenv; on Linux, clone the pyenv repository into ~/.pyenv and add it to your PATH; on Windows, clone pyenv-win and set its environment variables. Confirm with pyenv --version.

Pyenv is a tool that allows us to manage different versions of Python on our computer, making it easy to switch between versions as needed for the environment we are developing in.

What is pyenv used for?

Pyenv has multiple uses, providing developers with greater control over their projects, including:

  • Python Version Management: Allows installing, uninstalling, and switching between different Python versions without interfering with the original system Python installation (most Linux and some MacOS computers already have Python pre-installed; we call this the "system Python installation").

  • Environment Isolation: Combined with the pyenv-virtualenv plugin or venv, it enables developers to create specific Python environments for each project, ensuring that each project has its own dependencies and isolated packages.

  • Compatibility Testing: Facilitates testing code in different Python versions, ensuring compatibility and identifying potential issues.

  • Package Management: Each Python version installed with pyenv keeps its own packages, which you install with pip, so the specific version requirements of each project can be met.

Now let's look at the installation process for different operating systems.

Installing pyenv on Windows

Step 1: Install Git if you don't have it installed already. We recommend to read our guide on how to install git for windows or You can download it from the official page. The video tutorial is also recommended.

Step 2: Next step is to install pyenv-win. Open the Git Bash or PowerShell terminal and clone the pyenv repository from GitHub with the following command:

PowerShell
git clone https://github.com/pyenv-win/pyenv-win.git $HOME/.pyenv

📝 This will download the pyenv-win repository into a new directory called .pyenv that will live under your system user folder.

Step 3: Open the windows PowerShell command line and add PYENV, PYENV_HOME, and PYENV_ROOT to your environment variables with the following commands:

PowerShell
[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
 
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
 
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

Step 4: Add the following paths to your user's PATH variable to execute the pyenv command in the terminal:

PowerShell
[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

Step 5: Verify the installation. First, close the current terminal and open a new one, then run the following command to verify that pyenv is installed correctly:

PowerShell
pyenv --version

You should see something like this:

PowerShell
pyenv 3.1.1

If you want to learn more about pyenv on Windows, you can visit its official page.

Installing pyenv on Mac

Step 1: Install Xcode by opening the terminal and running the following command:

bash
xcode-select --install

If it's already installed, you will see a message like this:

bash
xcode-select: error: command line tools are already installed, use "Software Update" to install updates

Step 2: Install Homebrew. First, check if it's installed by running the following command:

bash
brew --version

If it's not installed, you will see a message like this:

bash
-bash: brew: command not found

To install it, run the following command:

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 3: To avoid errors during the installation of Python versions, install some libraries with the following command:

bash
brew install openssl readline sqlite3 xz zlib

Step 4: Install pyenv with the following command:

bash
brew install pyenv

Then load pyenv in your shell (zsh is the default shell on macOS; if you use bash, write to ~/.bash_profile instead):

bash
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Step 5: Verify the installation. First, close the current terminal and open a new one, then run the following command to verify that pyenv is installed correctly:

bash
pyenv --version

You should see something like this in your terminal:

bash
pyenv 2.3.23

If you want to learn more about pyenv on Mac, you can visit its official page.

Installing pyenv on Linux

Step 1: Before installing pyenv, install several necessary libraries and packages with the following command:

bash
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev \
git

Step 2: Clone the pyenv repository from GitHub by running the following command in the terminal:

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

Step 3: Configure the environment variables according to the shell you are using (e.g., ~/.bashrc, ~/.zshrc):

bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
zsh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc

Step 4: Verify the installation. First, close the current terminal and open a new one, then run the following command to confirm that pyenv is installed correctly:

bash
pyenv --version

You should see something like this in your terminal:

bash
pyenv 3.1.1

If you want to learn more about pyenv on Linux, you can visit its official page.

Tools like pyenv are very useful in the development world because they allow us to manage the Python versions installed on our computer. This enables us to work on different projects without worrying about the Python versions they require, thanks to the ease of installing and switching between versions. Incorporating this tool into your workflow will make you more productive, avoid compatibility errors, and make your development smoother. We invite you to read the 4Geeks Blog for more interesting content.

Switching Python versions with pyenv is the kind of setup professional developers handle every day. To learn to code in a structured program with real projects and mentors, compare the available learning paths.

Frequently asked questions

How do you install a Python version with pyenv?

Run pyenv install --list to see the available versions, then pyenv install followed by the version number you want. After the download and build finish, pyenv versions lists every interpreter pyenv manages. Installing a version does not activate it; select it with pyenv global for the whole user or pyenv local for the current project folder.

What is the difference between pyenv global and pyenv local?

pyenv global sets the default Python version for the user everywhere, while pyenv local writes a .python-version file in the current directory so that folder and its subfolders use a specific version. A third option, pyenv shell, changes the version only for the current terminal session. When several are set, shell takes priority over local, and local over global.

What is the difference between pyenv and venv?

pyenv manages which Python interpreters are installed and which one is active, while venv creates an isolated folder of packages on top of a single interpreter. They work well together: choose the Python version with pyenv, then run python -m venv .venv inside the project to keep its dependencies separate. Packages themselves are still installed with pip, not with pyenv.

Why does python still run the system version after installing pyenv?

The shell is not loading the pyenv shims, a folder that must come first in the PATH. On macOS and Linux, add eval "$(pyenv init -)" and the PYENV_ROOT lines to ~/.zshrc or ~/.bashrc, then open a new terminal. Also select a version with pyenv global, because the default is system. Afterwards, which python should point inside ~/.pyenv/shims.

Related guides