HowTo :: Install PyEnv (Simple Python Version Management)

Date:
Last Modified:
Reading Time: 3 mins
Section: HowTo
Categories: howto
Tags: linux python pyenv development

Introduction

Managing multiple Python versions on a single machine can be a nightmare. System tools often rely on a specific version of Python, and upgrading it can break your OS. PyEnv solves this by letting you easily install and switch between multiple isolated versions of Python.

In this guide, you will learn how to:

  1. Install PyEnv and its build dependencies
  2. Configure your shell to use PyEnv
  3. Install different Python versions
  4. Manage virtual environments easily

1. Establishing the Build Environment

PyEnv compiles Python from source. To do this, you need a set of build dependencies installed on your system.

Ubuntu / Debian

1
2
3
4
5

sudo apt update
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 python-openssl git

Fedora / RHEL

1
2

sudo dnf install make gcc zlib-devel bzip2 zlib-devel readline-devel \
sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel

2. Installing PyEnv

The easiest way to install PyEnv (along with useful plugins like pyenv-virtualenv) is using the automatic installer:

1

curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

3. Configuring Your Shell

This is the most critical step. PyEnv needs to be loaded in your shell environment to work.

For Bash Users (~/.bashrc)

Add the following lines to the end of your ~/.bashrc file:

1
2
3

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Then reload your shell:

1

source ~/.bashrc

For Zsh Users (~/.zshrc)

Add the following lines to the end of your ~/.zshrc file:

1
2
3

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Then reload your shell:

1

source ~/.zshrc

4. Basic Usage

Installing a Python Version

List available versions:

1

pyenv install --list

Install a specific version (e.g., 3.10.4):

1

pyenv install 3.10.4

Switching Versions

Global: Sets the default Python version for your user.

1
2
3

pyenv global 3.10.4
python --version 
# Output: Python 3.10.4

Local: Sets a Python version ONLY for the current directory (creates a .python-version file).

1
2
3
4

cd my_project_folder
pyenv local 3.9.1
python --version
# Output: Python 3.9.1 (only inside this folder)

5. Using Virtual Environments

The installer includes pyenv-virtualenv, which makes virtualenvs first-class citizens.

Create a virtualenv:

1
2

# Usage: pyenv virtualenv <python_version> <virtualenv_name>
pyenv virtualenv 3.10.4 my-project-env

Activate it automatically: Navigate to your project folder and set the local version to name of your virtualenv.

1
2

cd my_project_folder
pyenv local my-project-env

Now, whenever you enter my_project_folder, the virtual environment will strictly activate automatically!

6. Keeping PyEnv Updated

To update PyEnv to the latest version later on:

1

pyenv update

Troubleshooting