So lately I have been digging into learning Python for work and pleasure, and probably the FIRST tool that I had to come to grips with was virtualenv. The problem was that in order to learn it, I had to either READTHEDOCS(.com) or go through a tutorial. Reading docs just isn’t my thing, so I turned to tutorials … but most of them were incomplete, wrong or outdated, so here is my attempt at a better writeup.


Python uses libraries for darn near everything, and because you don’t want to run your apps with unnecessary libraries or environment variables, it’s best to try and keep each project completely separate. The downside is that the only other way (that I know of) to do this is to have a whole Vagrant instance for each project, and that’s just a waste.

Enter virtualenv, a simple lightweight python module that creates separate, instantiated environment’s for all of your projects (and brain farts!). PERIOD. It’s so simple, but that’s what makes it super useful!


These aren’t necessarily requirements, but they are the basics that I am working with as I got this up and running on my system:

  • OSX, Linux or WSL
  • Full root/system access
  • Knowledge of the Terminal (as in how to open it and the basics of how to use it)


In order to get the virtualenv package (as well as get other Python packages when we need them), we need PIP. PIP is a lot like Brew or Aptitude in that you type a few simple commands and poof, you have your payload. Get Pip by typing the following:


sudo easy_install pip

Debian-type Linux:

sudo apt install python3-pip

*We’re using sudo here because we want Pip to be available systemwide, much like Python already is.

Assuming it completes with no errors, let’s check the install by typing:


You should see something similar to:

Usage: pip COMMAND [OPTIONS] pip: error: You must give a command (use "pip help" to see a list of commands)

If you didn’t, you likely got an error, so I’d say stop and Google it. Assuming you don’t have an error, then let’s move on…


Now that Pip is installed, we need to go get the virtualenv package. Again, we want this to be available system wide, so sudo is used again:

MacOS & Debian-type Linux:

sudo pip install virtualenv

After that completes, let’s test it out by typing:


You should see the following, followed by a bunch of command-line switches and options:

You must provide a DEST_DIR Usage: virtualenv [OPTIONS] DEST_DIR


Ok, hold your horses, cuz we’re not done yet! While virtualenv runs, there’s a helper package that we want to install and configure that will seriously help us when we go to run this app in the future. The magic help script is……wait for it…… virtualenvwrapper!

This little script will allow us to make a centralized environment file folder in our users home directory as well as allow us to use shortcuts to activate our environments. To get this, type the following:

MacOS & Debian-type Linux:

sudo pip install virtualenvwrapper

We should also create the central storage folder for virtualenv because on some systems, it may whine at you if you don’t.

mkdir ~/.virtualenvs


In order for the helper scripts to be available for you from anywhere in your terminal, we need to add a line to your user profile file. If you aren’t entirely sure what this file does, then you probably shouldn’t be here in the first place as it is a fairly common core file that you should really know more about it, so I suggest going off to read on it.

To enable the features, you simply need to add the following line to your user profile file. The general default file that most linux distro’s use and MacOS uses is .bash_profile, ZSH uses .zshrc and some other distros use .bashrc. You will need to figure out which one your system uses.

Go ahead and add the following line anywhere in your file:

source /usr/local/bin/

Now we need to “apply” these changes. Do this by either logging out and logging back in or typing:

source ~/.bash_profile

*or whatever file your system uses.

This effectively runs everything in that file again. This can also be achieved by closing the terminal entirely and re-opening it.

And now, like all the rest of the commands, let’s test. Type the following in your terminal:


You should again see this (with options after):

You must provide a DEST_DIR Usage: virtualenv [OPTIONS] DEST_DIR

If everything went as planned, then we should be all good. You can now sandbox to your heart’s content!


This is some of the info that others left off, and some of what I was missing from my understanding of this tool. By default, virtualenv wants to create a new folder where ever you are in the system and place all of the related files inside that directory. This is generally bad as you have to ONLY reference THOSE files from that specific directory, and it makes your repo’s all cluttered (unless you .gitignore) them as well. VIRTUALENVWRAPPER however stores all of the virtual environments under ~/.virtualenvs/ , which is much cleaner and easier to handle.


To make a new environment, simply type:

mkvirtualenv *your_cool_project_name*

It will install local python and any other libraries, then poof, you are all set!


One of the cool parts about the wrapper helper is the ability to use the workon command. That command effectively activates the specified virtualenv. You can use this by typing:

workon *your_cool_project_name*

Obviously the project must have been created prior to using this or else it will fail.

To deactivate, you simply type:


There’s a cool series of folders in your ~/.virtualenvs/ that cover adding in scripts or commands to be run whenever you activate or deactivate (as well as pre or post) any virtualenv’s. I haven’t had a ton of time to go through these on my own yet, but the docs are actually best for this section. I’ll update this post once I have a little more knowledge under my belt.

Now, go forth and Python-On!