Managing Python Virtual Environments using Virtualenvwrapper

6 min readJul 25, 2023

In my recent article, I demonstrated why and how to manage virtual environments in Python using virtualenv. One of the drawbacks of using virtualenv is you cannot have your virtual environments in one directory, at least not automatically. This may lead to you having virtual environments all over the place and being unable to differentiate one from another.

Another challenge that comes with virtualenv is that it lacks commands for activating virtual environments without having to locate the activate script.

In this article, we shall look at another tool called virtualenvwrapper that addresses some of the challenges experienced in virtualenv and venv. Virtualenvwrapper enables Python developers to manage multiple virtual environments and create, copy, and delete these environments among other functionalities. Let’s get started with it.

Installing Virtualenvwrapper only requires a few of the actions that are shown in this section. We shall be using Linux in this tutorial. Make sure Python is installed on your computer as the first step. Alternatively, see these posts:

To install virtualenvwrapper, open your terminal and run the following command.

pip install virtualenvwrapper

Here is the output from the terminal

Collecting virtualenvwrapper
 Downloading virtualenvwrapper-4.8.4.tar.gz (334 kB)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 334.9/334.9 kB 695.1 kB/s eta 0:00:00
 Preparing metadata (setup.py) ... done
Collecting virtualenv
 Downloading virtualenv-20.24.2-py3-none-any.whl (3.0 MB)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.0/3.0 MB 709.1 kB/s eta 0:00:00
Collecting virtualenv-clone
 Downloading virtualenv_clone-0.5.7-py3-none-any.whl (6.6 kB)
Collecting stevedore
 Downloading stevedore-5.1.0-py3-none-any.whl (49 kB)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 49.6/49.6 kB 1.0 MB/s eta 0:00:00
Collecting pbr!=2.1.0,>=2.0.0
 Using cached pbr-5.11.1-py2.py3-none-any.whl (112 kB)
Collecting platformdirs<4,>=3.9.1
 Downloading platformdirs-3.9.1-py3-none-any.whl (16 kB)
Collecting distlib<1,>=0.3.7
 Downloading distlib-0.3.7-py2.py3-none-any.whl (468 kB)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 468.9/468.9 kB 917.9 kB/s eta 0:00:00
Collecting filelock<4,>=3.12.2
 Downloading filelock-3.12.2-py3-none-any.whl (10 kB)
Building wheels for collected packages: virtualenvwrapper
 Building wheel for virtualenvwrapper (setup.py) ... done
 Created wheel for virtualenvwrapper: filename=virtualenvwrapper-4.8.4-py2.py3-none-any.whl size=24855 sha256=46c1ba55a1f3af6891997f740c8f9e4c9e4b7c3d5ee86e64b3a1d0f0d655fc22
 Stored in directory: /root/.cache/pip/wheels/ae/9c/dd/513e674faa97f3ac6dfda663b7bb5d23df9019258e871bb6d4
Successfully built virtualenvwrapper
Installing collected packages: distlib, virtualenv-clone, platformdirs, pbr, filelock, virtualenv, stevedore, virtualenvwrapper
Successfully installed distlib-0.3.7 filelock-3.12.2 pbr-5.11.1 platformdirs-3.9.1 stevedore-5.1.0 virtualenv-20.24.2 virtualenv-clone-0.5.7 virtualenvwrapper-4.8.4

Alternatively, if you intend to use it globally across all Python environments, use the sudo command (requires administrative privileges).

sudo pip install virtualenvwrapper

Now, you should have a virtualenvwrapper installed on your machine. To check whether it is installed, run the following command.

whereis virtualenvwrapper

Which prints out the location for virtualenvwrapper

virtualenvwrapper: /usr/local/bin/virtualenvwrapper.sh

Another way to test its installation is by using the pip show command used in the previous tutorial.

pip show virtualenvwrapper

which outputs details as shown

Name: virtualenvwrapper
Version: 4.8.4
Summary: Enhancements to virtualenv
Home-page: https://virtualenvwrapper.readthedocs.io/
Author: Doug Hellmann
Author-email: doug@doughellmann.com
License: MIT
Location: /usr/local/lib/python3.10/site-packages
Requires: stevedore, virtualenv, virtualenv-clone
Required-by:

The next step should be to configure the virtualenvwrapper-specific startup scripts which can be added to the script that is executed when a user logs in, the .bashrc file or the user profile-specific configuration, the .profile file. Both of the scripts are located in your home directory. You can use any editor of your choice i.e. Vim, Emacs, gedit or nano etc.

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devprojects
source /usr/local/bin/virtualenvwrapper.sh

WORKON_HOME — Optional setting that directs virtualenvwrapper on where to place the virtual environments which will be created.

PROJECT_HOME — Directs virtualenvwrapper on where to place the project working directories. Note that this folder must be existing otherwise an error will be thrown.

You can now reload the startup file using

source ~/.bashrc

Which outputs

virtualenvwrapper.user_scripts creating /root/.virtualenvs/premkproject
virtualenvwrapper.user_scripts creating /root/.virtualenvs/postmkproject
virtualenvwrapper.user_scripts creating /root/.virtualenvs/initialize
virtualenvwrapper.user_scripts creating /root/.virtualenvs/premkvirtualenv
virtualenvwrapper.user_scripts creating /root/.virtualenvs/postmkvirtualenv
virtualenvwrapper.user_scripts creating /root/.virtualenvs/prermvirtualenv
virtualenvwrapper.user_scripts creating /root/.virtualenvs/postrmvirtualenv
virtualenvwrapper.user_scripts creating /root/.virtualenvs/predeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/postdeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/preactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/postactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/get_env_details

Please note that your printed paths could be different from what is shown above. Virtualenvwrapper has successfully been set up for use.

Virtualenvwrapper In Use

There are commands that can be run directly from the terminal, the most common ones being:

workon — Activates/deactivates and switches between multiple virtual environments.
mkvirtualenv — Creates a new virtual environment.
mktmpenv — Create a temporary virtual environment.
rmvirtualenv — Removes an existing virtual environment
mkproject — Project directory management command for creating a new virtual environment in the preset (PROJECT_HOME) directory.
rmproject — Remove existing project.
lsvirtualenv — List all the environments.
deactivate — Deactivate an active virtual environment and switch back to global/system-based Python.

Creating a New Virtual Environment

To create a new virtual environment, run the command

mkvirtualenv mywebproject

Output:

created virtual environment CPython3.10.10.final.0-64 in 357ms
 creator CPython3Posix(dest=/root/.virtualenvs/mywebproject, clear=False, no_vcs_ignore=False, global=False)
 seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/root/.local/share/virtualenv)
 added seed packages: pip==23.2.1, setuptools==68.0.0, wheel==0.41.0
 activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
virtualenvwrapper.user_scripts creating /root/.virtualenvs/mywebproject/bin/predeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/mywebproject/bin/postdeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/mywebproject/bin/preactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/mywebproject/bin/postactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/mywebproject/bin/get_env_details
(mywebproject) $

You will notice the active virtual environment by the name in parentheses before the shell prompt as shown above. Next, you can confirm the location of Python and pip versions being used as shown.

(mywebproject) $which python
/root/.virtualenvs/mywebproject/bin/python
(mywebproject) $which pip
/root/.virtualenvs/mywebproject/bin/pip
(mywebproject) $

At this point, a new virtual environment has been created and you can proceed with installing packages and customizing your project to your preference. The basic commands as those of virtualenv can be used, for example, deactivating the virtual environment can be done by running the deactivate command.

Creating a Temporary Virtual Environment

Virtualenvwrapper supports the creation of a temporary virtual environment that is different from the usual virtual environment. The difference is that a temporary virtual environment is not persisted in your machine. Once exited, it is deleted. To create a temporary virtual environment, run the following:

Output:

created virtual environment CPython3.10.10.final.0-64 in 131ms
 creator CPython3Posix(dest=/root/.virtualenvs/tmp-e41944ffcc2447c, clear=False, no_vcs_ignore=False, global=False)
 seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/root/.local/share/virtualenv)
 added seed packages: pip==23.2.1, setuptools==68.0.0, wheel==0.41.0
 activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
virtualenvwrapper.user_scripts creating /root/.virtualenvs/tmp-e41944ffcc2447c/bin/predeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/tmp-e41944ffcc2447c/bin/postdeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/tmp-e41944ffcc2447c/bin/preactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/tmp-e41944ffcc2447c/bin/postactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/tmp-e41944ffcc2447c/bin/get_env_details
This is a temporary environment. It will be deleted when you run 'deactivate'.
(tmp-e41944ffcc2447c) $

Notice the prefix ‘tmp’ in the name of the virtual environment. This can be a good approach especially if you are just testing some packages or for demonstration purposes only. In short, if you do not need to persist the virtual environment folders and files, then this would be your preferred approach.

This is what happens from the terminal when you deactivate the virtual environment.

(tmp-e41944ffcc2447c) $deactivate
Removing temporary environment: tmp-e41944ffcc2447c
Removing tmp-e41944ffcc2447c...

Creating a Project

Virtualenvwrapper also supports creating projects using mkproject which requires the project directory to have been set in the startup script as PROJECT_HOME and already existing. If not, this is what the terminal shows.

$mkproject pythonproject
ERROR: Project directory '/root/Devprojects' does not exist. Create it or set PROJECT_HOME to an existing directory.

To fix this error let’s create the directory at /root/Devprojects

mkdir /root/Devprojects

Then re-run the previous command mkproject pythonproject which outputs successfully as shown.

created virtual environment CPython3.10.10.final.0-64 in 158ms
 creator CPython3Posix(dest=/root/.virtualenvs/pythonproject, clear=False, no_vcs_ignore=False, global=False)
 seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/root/.local/share/virtualenv)
 added seed packages: pip==23.2.1, setuptools==68.0.0, wheel==0.41.0
 activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
virtualenvwrapper.user_scripts creating /root/.virtualenvs/pythonproject/bin/predeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/pythonproject/bin/postdeactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/pythonproject/bin/preactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/pythonproject/bin/postactivate
virtualenvwrapper.user_scripts creating /root/.virtualenvs/pythonproject/bin/get_env_details
Creating /root/Devprojects/pythonproject
Setting project for pythonproject to /root/Devprojects/pythonproject

Activating an already existing project or switching between projects can be also achieved by the workon command.

$workon mywebproject
(mywebproject) $

Listing Virtual Environments

A listing of existing virtual environments can be achieved using:

$lsvirtualenv 
mywebproject
============


pythonproject
=============

Virualenvwrapper simplifies the process of working with virtual environments, streamlines your workflow, and enhances Python project management, making it a valuable tool for Python developers. Some of the key advantages discussed in this article include:

Centralized Location: By default, virualenvwrapper creates all virtual environments in a centralized location, making it easier to organize and manage them. This avoids cluttering your project directories with virtual environment folders.
Workon Home: Virualenvwrapper allows you to specify a custom location for virtual environments using the WORKON_HOME variable. This feature lets you keep your virtual environments separate from the default location, providing better organization and management.
Integration with System Python: Unlike virualenvwrapper, which requires you to run specific Python scripts to activate an environment, virualenvwrapper integrates with the system’s Python interpreter. This means you can use the workon command directly from any shell without needing to source an activation script.
Ease of Use: Virualenvwrapper simplifies the creation and management of virtual environments. With straightforward commands like mkvirtualenv, workon, and rmvirtualenv, you can easily create, switch between, and delete virtual environments.

For further reading, please refer to the following:

In our next article, we shall be looking at an alternative tool for managing virtual environments in Python, expanding our knowledge and understanding of the interesting provisions of Python programming language.