Master Python Version Management with pyenv and virtualenv: A Complete Guide

Preface

In daily development you may encounter projects using different Python versions—e.g., Project A on Python 2.7, Project B on Python 3.10.4 with requests==2.25.1, and Project C on Python 3.10.4 with requests==2.27.1. Managing multiple interpreter versions and package versions can become cumbersome, and the best solution is to use separate virtual environments.

What is pyenv?

pyenv is a Python version management tool forked from the Ruby community. It lets you switch the global Python interpreter easily and works with virtualenv to manage packages. After installing pyenv, it adds a shims directory to your $PATH:

❯ echo $PATH
/Users/allenjol/.pyenv/plugins/pyenv-virtualenv/shims:/Users/allenjol/.pyenv/shims:/usr/local/bin:/usr/local/sbin

By inserting the shims path at the beginning of PATH, pyenv controls which Python version is invoked.

pyenv, virtualenv, and pipenv

pyenv manages interpreter versions, virtualenv is a mature tool for creating isolated Python environments, and pipenv (created by the author of requests) is another package manager that can also generate virtual environments. This article focuses on pyenv and virtualenv.

Installing pyenv

CentOS 7

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

macOS

brew update
brew install pyenv

If brew fails due to network issues, you can switch sources or configure a proxy as described in the linked article.

Setting environment variables

# Bash
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
source ~/.bashrc

# Zsh (iTerm2 + Zsh)
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
source ~/.zshrc

Check pyenv version

pyenv --version

Command‑line usage

# Show current version
pyenv version
# List all installed versions
pyenv versions
# List installable versions
pyenv install --list
# Install Python 3.10.4
pyenv install 3.10.4
# Rehash after installation
pyenv rehash
# Uninstall a version
pyenv uninstall 3.10.4
# Switch global version to system Python
pyenv global system
# Switch to pyenv‑managed 3.10.4
pyenv global 3.10.4

pyenv‑virtualenv plugin

Linux installation

git clone https://github.com/yyuu/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv
# Configure
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile
source ~/.bash_profile

macOS installation

# Clone plugin
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
# Zsh configuration
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
exec "$SHELL"
# Or install via Homebrew
brew install pyenv-virtualenv
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
exec "$SHELL"

Using pyenv‑virtualenv

# Create a virtual environment
pyenv virtualenv venv3.10.4
# Activate it
pyenv activate venv3.10.4
pyenv version
# Deactivate
pyenv deactivate venv3.10.4
# Remove the environment
pyenv uninstall venv3.10.4

When you switch to a Python virtual environment, both pip and the installed packages are isolated from the system environment, providing clean interpreter and package version separation.