Install virtualenvwrapper in Python

Managing Python environments can get messy fast. That is why tools like virtualenvwrapper exist. It makes working with virtual environments simple and organized.

In this guide, you will learn how to install virtualenvwrapper step by step. You will also learn how to configure it and use it in your daily workflow.

What Is virtualenvwrapper?

virtualenvwrapper is a set of shell scripts built on top of virtualenv. It gives you simple commands to create, delete, and switch between virtual environments.

Instead of remembering long paths, you just type a short command. All your environments live in one central place. This keeps your projects clean and separate.

It works on Linux, macOS, and Windows. On Windows, you use a version called virtualenvwrapper-win.

Why Use virtualenvwrapper?

Plain virtualenv works fine, but it has some annoyances. You must activate environments by typing full paths. You also have to store them wherever you like, which can get confusing.

virtualenvwrapper solves these problems. Here are the main benefits:

Central storage keeps all environments in one folder. Short commands save you typing. Easy switching lets you jump between projects quickly.

It also supports hooks. Hooks are scripts that run automatically when you create or activate an environment. This is great for setting project-specific settings.

Prerequisites

Before you start, make sure you have a few things ready. You need Python installed on your system. You also need pip, the Python package manager.

Check your Python version with this command:

python3 --version

You should see output like this:

Python 3.11.4

Also check that pip is available:

pip3 --version

If both commands work, you are ready to continue.

Step 1: Install virtualenv

virtualenvwrapper depends on virtualenv. So you must install virtualenv first. Run this command:

pip3 install virtualenv

Wait for the installation to finish. You should see a message saying it was installed successfully.

Step 2: Install virtualenvwrapper

Now install virtualenvwrapper itself. Use pip again:

pip3 install virtualenvwrapper

On Windows, the package name is different. Use this instead:

pip install virtualenvwrapper-win

After this step, the tool is on your system. But it is not ready to use yet. You still need to configure it.

Step 3: Configure Your Shell

virtualenvwrapper needs some environment variables. These tell it where to store your environments.

You must add a few lines to your shell startup file. This file is usually .bashrc or .zshrc in your home folder.

Open the file with a text editor. Then add these lines:

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source /usr/local/bin/virtualenvwrapper.sh

Let me explain what each line does. WORKON_HOME is where your environments are stored. PROJECT_HOME is where your project code lives.

VIRTUALENVWRAPPER_PYTHON points to the Python interpreter to use. The last line loads the wrapper scripts.

The path to virtualenvwrapper.sh may differ on your system. You can find it with this command:

which virtualenvwrapper.sh

Example output:

/usr/local/bin/virtualenvwrapper.sh

Use the path you get in your startup file. Then reload the file:

source ~/.bashrc

Step 4: Verify the Installation

Now check that everything works. Type this command:

mkvirtualenv --help

If you see a help message, the installation worked. If you see an error, check your startup file again.

Common issues include wrong paths or a missing virtualenvwrapper.sh file. Fix those and reload your shell.

Step 5: Create Your First Environment

Creating an environment is easy. Just run this command:

mkvirtualenv myproject

This creates a new environment named myproject. It also activates it right away.

You will see your prompt change. It now shows the environment name in front:

(myproject) user@host:~$

Now any package you install goes into this environment. Your system Python stays untouched.

Essential virtualenvwrapper Commands

Here are the commands you will use most often. Learn these and you are set.

The workon command lists all environments. It also activates one if you give a name.

workon
workon myproject

The deactivate command exits the current environment. You go back to your normal shell.

deactivate

The rmvirtualenv command deletes an environment you no longer need.

rmvirtualenv myproject

The lsvirtualenv command lists all environments with more detail.

lsvirtualenv

The cdvirtualenv command takes you to the environment folder. This is handy for checking installed packages.

cdvirtualenv

Installing Packages Inside an Environment

Once your environment is active, install packages with pip. For example, install requests:

pip install requests

You can also save your packages to a file. This helps others set up the same environment.

pip freeze > requirements.txt

Later, anyone can install them with:

pip install -r requirements.txt

Using Hooks for Automation

Hooks let you run scripts automatically. They live in the $WORKON_HOME folder. Common hook names include postmkvirtualenv and predeactivate.

For example, a postmkvirtualenv hook can install your favorite tools in every new environment. This saves time and keeps things consistent.

Just create the file and make it executable. virtualenvwrapper runs it at the right moment.

Common Problems and Fixes

Sometimes the source command fails. This usually means the path is wrong. Run the which command again to find the real path.

Another issue is that commands are not found after reloading. Make sure you added the lines to the correct startup file. Bash uses .bashrc, while Zsh uses .zshrc.

On macOS, the system Python may not work well. Use Homebrew Python instead. Point VIRTUALENVWRAPPER_PYTHON to that version.

On Windows, the commands are slightly different. You use workon and mkvirtualenv the same way, but setup uses the win package.

Conclusion

virtualenvwrapper makes Python environment management much easier. You install it once, configure your shell, and then enjoy short, simple commands.

In this guide, you learned how to install virtualenvwrapper, set it up, and use its main commands. You also saw how to fix common problems.

Now you can keep your projects clean and separate. Try it on your next Python project and see the difference.