Installing virtualenv and virtualenvwrapper

This recipe will enable you to manage different versions of different libraries for multiple projects. We use virtualenv to create virtual Python environments to host collections of project-specific libraries in an isolated directory. For example, you may have an old legacy project using Django 1.4, whereas a new project requires you use Django version 1.8. With virtualenv, you can have both versions of Django installed on the same machine, and each project can access the appropriate version of Django without any conflicts or problems.

Without virtualenv, you are forced to either upgrade the old project or find a workaround to implement the new features of the other version, therefore limiting or complicating the new project.

The virtualenv allows you to simply switch between different Python virtual environments for your individual projects. This has the added benefit that you can easily and quickly set up a new machine for testing or help a new developer get their machine up and running as fast as possible.

Getting ready

Before anything, we are going to assume that you already have a Linux/Ubuntu machine or a virtualbox instance running Linux/Ubuntu so you can follow these instructions.

Tip

I also suggest trying out Vagrant (http://www.vagrantup.com), which uses virtualbox to box and standardize your development environment.

Ubuntu 14.04 comes with Python 2.7.6 and Python 3.4 preinstalled; the other libraries are your responsibility as explained in the following sections.

Windows users need to download and install Python 2.7.x from the Python home page at https://www.python.org/downloads/windows/; please download the newest version of the 2.7.x series since this book is written with 2.7.X in mind. The installer includes a bundled version of pip, so make sure you install it!

Take a close look at the correct version to download, making sure that you get either the 32-bit or 64-bit download. You cannot mix and match the versions, so be careful and remember to install the correct version.

A great site for other kinds of Windows binaries can be found at http://www.lfd.uci.edu/~gohlke/pythonlibs/. Wheel files are the new norms of installations and can be executed from the command line as follows:

python pip install libraryName.whl

Note

On Windows, make sure that your Python interpreter is set up on your system path. This way, you can simply call Python directly from the command prompt using the C:\Users\Michael> python filename.py command. If you need more help, information can be found by following one of the online instructions at https://pypi.python.org/pypi/pip.

As of Python 2.7.9 and later versions, pip is available on installation.

Python 3 would be awesome to use, and for many Python GIS libraries, it is ready for show time. Unfortunately, not all GIS libraries jive with Python 3 (pyproj) as one would love to see at the time of writing this. If you want, feel free to go for Python 3.x and give it a go. A great webpage to check the compatibility of a library can be found at https://caniusepython3.com/.

To install virtualenv, you need to have a running installation of Python and pip. The pip package manager manages and installs Python packages, making our lives easier. Throughout this book, if we need to install a package, pip will be our tool of choice for this job. The official installation instructions for pip can be found at https://pip.pypa.io/en/latest/installing.html. To install pip from the command line, we first need to install easy_install. Let's try it out from the Terminal:

$ sudo apt-get install python-setuptools python-pip

With this one line, you have both pip and easy_install installed.

Note

What is sudo?

sudo is a program for Unix-like computer operating systems that allows users to run programs with the security privileges of another user (normally, the super user or root). Its name is a concatenation of su (substitute user) and do (take action). Take a look at http://en.wikipedia.org/wiki/Sudo for more information on this.

The command sudo means to run an execution as a super user. If this fails, you will need to get theez_setup.py file, which is available at https://bootstrap.pypa.io/ez_setup.py. After downloading the file, you can run it from the command line:

$ python ez_setup.py

Now pip should be up and running and you can execute commands to complete the installations of virtualenv and virtualenvwrapper. The virtualenvwrapper creates shortcuts that are faster ways to create or delete your virtual environments. You can test it as follows:

$ pip install virtualenv

How to do it...

The steps to install your Python virtualenv and virtualenvwrapper packages are as follows:

1. Install virtualenv using the pip installer:

   $ sudo pip install virtualenv
   

2. Install virtualenvwrapper using easy_install:

   $ sudo easy_install virtualenvwrapper
   

   Note

   We use easy_install instead of pip because with Ubuntu 14.04, the virtualenvwrapper.sh file is unfortunately not located at /usr/local/bin/virtualenvwrapper.sh where it should be according to the online documentation.

3. Assign the WORKON_HOME variable to your home directory with the folder name venvs. Create a single folder where you want to store all your different Python virtual environments; in my case, the folder is located at /home/mdiener/venvs:

   $ export WORKON_HOME=~/venvs
   $ mkdir $WORKON_HOME
   

4. Run the source command to execute the virtualenvrapper.sh bash file:

   $ source /usr/local/bin/virtualenvwrapper.sh
   

5. Next, we create a new virtual environment called pygeoan_cb, and this is also the name of the new folder where the virtual environment is installed:

   $ mkvirtualenv pygeoan_cb
   

   To use virtualenvwrapper the next time you start up your machine, we need to set it up so that your bash terminal runs the virtualenvwrapper.sh script when your computer starts.

6. First, put it in your ~/.bashrc file:

   $ echo "export WORKON_HOME=$WORKON_HOME" >> ~/.bashrc
   

7. Next, we'll import the virtualenvwrapper function in our bash:

   $ echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
   

8. Now we can execute our bash:

   $ source ~/.bashrc
   

How it works...

Step one shows how pip installs the virtualenv package into your system-wide Python installation. Step two shows how the virtualenvwrapper helper package is installed with easy_install because the virtualenvwrapper.sh file is not created using the pip installer. This will help us create, enter, and generally, work or switch between Python virtual environments with ease. Step three assigns the WORKON_HOME variable to a directory where we want to have all of our virtual environments. Then, we'll create a new directory to hold all the virtual environments. In step four, the command source is used to execute the shell script to set up the virtualenvwrapper package. In step five, we see how to actually create a new virtualenv called pygeoan_cb in our /home/mdiener/venvs directory. This final step automatically starts our virtualenv session.

Once the virtualenv session starts, we can now see the name of virtualenv in brackets like this:

(pygeoan_cb)mdiener@mdiener-VirtualBox:~$

To exit virtualenv, simply type the following code:

$ deactivate

Now, your command line should be back to normal as shown here:

mdiener@mdiener-VirtualBox:~$

To reactivate virtualenv, simply type:

$ workon pygeoan_cb

Tip

The workon command has Tab completion. So, simply type workon, and then the first letter of the name of the virtual environment you want to enter, such as py. Hit Tab and it will autocomplete the name.

Inside the /venvs folder, you will find specific individual virtual environments for each project in the form of a subfolder. The virtualenvwrapper package will always create a new folder for each new project you create. You can, therefore, easily delete a folder and it will remove your virtual environment.

To quickly print a list all of the installed libraries to a file, we'll use the pip command:

$ pip freeze > requirements.txt

This will create a text file called requirements.txt in the current folder. The text file contains a list of all the installed Python packages inside the Python virtual environment currently running.

To create a new virtualenv from a requirements file, use the following command:

$ pip install -r /path/to/requirements.txt

There's more…

For those of you who are just starting out with geospatial Python development, it should be noted that you should keep your project-specific code at another location outside your Python virtual environment folder. For example, I always have each project-related code contained in a separate folder called 01_projects, which is my main folder. The path to my projects folder is /home/mdiener/01_projects, and the structure of two of my projects is as follows:

• 01_projects/Name_project1
• 01_projects/Name_project2

All virtual environments are located under /home/mdiener/venvs/. Usually, I give them the same name as a project to keep things organized, as follows:

• /home/mdiener/venvs/Name_project1
• /home/mdiener/venvs/Name_project2