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

:

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

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

<code>git clone https://github.com/pyenv/pyenv.git ~/.pyenv
</code>

macOS

<code>brew update
brew install pyenv
</code>

If

brew

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

Setting environment variables

<code># 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
</code>

Check pyenv version

<code>pyenv --version
</code>

Command‑line usage

<code># 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
</code>

pyenv‑virtualenv plugin

Linux installation

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

macOS installation

<code># 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"
</code>

Using pyenv‑virtualenv

<code># 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
</code>

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.