Mastering Python Environments on Ubuntu: A Beginner's Guide to Installing and Setting up Virtualenvwrapper with Python 3 and Pip 23

Virtualenvwrapper is an extension package built on top of virtualenv. It offers a a convenient way of set of dealing with virtual environments effectively, especially if you often have to create, delete or swap between. It alloww you to work on multiple python projects simultaneously without conflicting dependencies.

In this article, I will guide you through the process of installing and setting up virtualenvwrapper on Ubuntu 22.04 or later, with Python 3.10 and pip 23.


Before we start, you need to have the following prerequisites:

  • Ubuntu 22.04 or later installed on your system

  • Python 3.10 installed on your system

  • pip 23 installed on your system

If you do not have Python 3.10 and pip 23 installed, you can install them by running the following commands:

sudo apt update
sudo apt install python3.10 python3-pip

Installing virtualenvwrapper

First, we need to install virtualenvwrapper using pip. Run the following command:

$ pip install virtualenvwrapper

This will install virtualenvwrapper and its dependencies.

Configuring virtualenvwrapper

Once you have installed virtualenvwrapper, you need to configure it. First, create a directory where you want to store your virtual environments. For our case we will be creating the directory .virtualenvs in our home directory:

$ mkdir ~/.virtualenvs

Next, add the following variables to your shell startup script, these are normally ~/.bashrc or ~/.bash_profile file to set the environment variables for virtualenvwrapper:

export WORKON_HOME="$HOME/.virtualenvs"
export VIRTUALENVWRAPPER_PYTHON="/usr/bin/python3"
export VIRTUALENVWRAPPER_VIRTUALENV="$HOME/.local/bin/virtualenv"
source $HOME/.local/bin/

The virtual environments will be installed under the WORKON_HOME directory instead of the same directory as the project. The source $HOME/.local/bin/ ensures that virtualenvwrapper is loaded and accessible whenever you open a new terminal session. It sets up the environment so that you can easily utilize the virtualenvwrapper commands and manage your virtual environments.

Save and close the ~/.bashrc file. Then, source the startup script to reload the configuration or open up a new terminal session:

source ~/.bashrc

Creating a virtual environment

Now that virtualenvwrapper is installed and configured, you can create a virtual environment for your project. To create a virtual environment, use the mkvirtualenv command followed by a qualified python environment name. A qualified Python environment name typically follows a specific format. It can include alphanumeric characters, underscores (_), and hyphens (-). However, it is important to note that the name cannot start with a hyphen (-) or contain spaces. Examples of a qualified enviroment name are: myenv, project_env, dev-environment, or python3env. Create a new environment with the name myenv as shown below.

> $ mkvirtualenv myenv

This will create a new virtual environment named myenv . Your output should be similar to the one below (screenshot cropped for brevity):

For more information on virtual environments and naming conventions, you can refer to the official Python documentation on virtual environments:

Using a virtual environment

To use the virtual environment, simply activate it using the workon command followed by the name of the environment.

workon myenv

This will activate the myenv environment, and any Python packages installed will be installed in the virtual environment, rather than globally. Python packages can be installed using the using the normal pip install <package_name> command.

List of available commands

  1. lsvirtualenv: The lsvirtualenv command allows you to list all the available virtual environments created using virtualenvwrapper.

  2. mkvirtualenv: The mkvirtualenv command is used to create a new virtual environment. By specifying a name after the command, such as "myenv" in the example provided, a new virtual environment with that name will be created.

  3. workon: The workon command is used to activate a specific virtual environment. By specifying the name of the environment after the command, such as "myenv" in the example, the corresponding environment will be activated, and any Python packages installed will be associated with that environment.

  4. deactivate: The deactivate command is used to exit or deactivate the current virtual environment and return to the global system environment.

  5. rmvirtualenv: The rmvirtualenv command allows you to remove a virtual environment. By specifying the name of the environment after the command, such as "myenv" in the example, the corresponding environment will be deleted.

These commands provide a comprehensive set of tools for creating, swapping, managing, and working with virtual environments using virtualenvwrapper.


In conclusion, virtualenvwrapper is a powerful tool that enhances the management of virtual environments in Python development. By following the installation and setup instructions provided in this article, you can easily create, switch between, and delete virtual environments, enabling you to work on multiple Python projects simultaneously without conflicts in dependencies.

With virtualenvwrapper, you can maintain clean and organized project setups, isolate packages and dependencies, and ensure consistent environments across different machines. By utilizing virtualenvwrapper, you gain more control over your Python projects and can enjoy the benefits of a streamlined development workflow.

For further details and additional resources on virtual environments, naming conventions, and best practices, I recommend referring to the official Python documentation on virtual environments and virtualenvwrapper documentation.

Embrace virtualenvwrapper and elevate your Python development experience to new heights!