Managing Python Virtual Environments with pyenv-virtualenv

In my previous post I had explained how we could use pyenv to manage multiple versions of Python with ease. This post is a follow up and it explains how to manage virtual environments with pyenv-virtualenv.

pyenv-virtualenv is a plugin of pyenv. It extends pyenv with features to manage virtual environments.

I will provide an overview of the installation and usage of pyenv-virtualenv. The installation instructions are for Mac OS X and Homebrew. If you are not on Mac OS X or don't use Homebrew, refer to the pyenv-virtualenv documentation for installation instructions specific to your system. The rest of the post is about the usage of pyenv-virtualenv and is applicable to everyone.

Installing pyenv-virtualenv

pyenv-virtualenv requires pyenv. If you have not installed pyenv yet, follow the instructions in my previous post to first install pyenv.

Installing pyenv-virtualenv on Mac OS X with Homebrew is just as simple as installing pyenv.

$ brew install pyenv-virtualenv

After installation, add the following at the bottom of your profile (~/.bash_profile or ~/.zshenv)

if which pyenv-virtualenv-init > /dev/null; then eval "$(pyenv virtualenv-init -)"; fi

Finally, restart your shell so the profile changes can take effect.

Using pyenv-virtualenv

Using pyenv-virtualenv to work with virtual environments is very straightforward.

pyenv virtualenv

Create a virtual environment for a specific Python version.

$ pyenv virtualenv 3.4.3 my_env_3_4

This will create a virtual environment based on Python 3.4.3 under the pyenv root in a directory called my_env_3_4.

Create a virtual environment based on the current Python version.

$ pyenv version
2.7.10 (set by /Users/akbar/.pyenv/version)

$ pyenv virtualenv my_env_2_7

This will create a virtual environment based on Python 2.7.10 under the pyenv root in a directory called my_env_2_7.

pyenv virtualenvs

List existing virtual environments created by pyenv.

$ pyenv virtualenvs
my_env_2_7 (created from /Users/akbar/.pyenv/versions/2.7.10)
my_env_3_4 (created from /Users/akbar/.pyenv/versions/3.4.3)

The pyenv versions command will also show the virtual environments along with the installed versions of Python.

$ pyenv versions
* 2.7.10 (set by /Users/akbar/.pyenv/version)

pyenv activate/deactivate

If you have followed the installation instructions given above or the instructions specific to your system in the pyenv-virtualenv documentation, eval "$(pyenv virtualenv-init -)" should be property configured in your shell. Now, pyenv-virtualenv will automatically activate and deactivate the virtual environment on entering and leaving directories that contain a .python-version file with a valid virtual environment.

If required you can manually activate and deactivate virtual environments too.

To manually activate a virtual environment.

$ pyenv activate my_env_2_7

To manually deactivate a virtual environment.

(my_env_2_7)$ pyenv deactivate

pyenv uninstall

Delete a virtual environment.

$ pyenv uninstall my_env_2_7

This will delete the virtual environment directory from under the pyenv root directory.