Overview
Recently I was trying to write a script that had dependencies on pip packages. Now, I am fortunate enough to know that it’s a bad idea to install pip packages globally (especially using sudo), so I set about to find the best way to install those dependencies without breaking my system.
I’d heard about virtualenv (Virtual Environment) before, and after a quick google this seemed to be the solution I needed.
Simply put, a virtualenv is a secluded environment (directory) where you install the dependencies your application requires so that it can’t interfere with the rest of your operating system (and its’ possible separate dependencies).
However, installing and using virtualenv seemed far too complicated, especially for a python newbie like myself.
This post is meant as a “Python Virtualenv for Dummies”; both so that I have a quick document to refer back to, and hopefully to help those as helpless as I am.
Note that this post uses an installation of Ubuntu 18.04 with Python v3.6. If you were wanting to install Virtualenv for Python 2 instead, simply remove the “3” off the end of the install commands.
Installation
First up is installing python and pip, both of which are done through apt:
$ sudo apt-get install python3 python3-pip
Next is installing virtualenv using pip. We’ll install this only for our user, so we don’t need to use sudo:
$ pip3 install --user virtualenv
Using Virtualenv
First we need to create an environment, this is done in the root directory of your project:
$ cd /path/to/project/dir
$ virtualenv venv
New python executable in venv/bin/python
Installing setuptools, pip, wheel...done.
The only argument supplied to the command is the subdirectory to create within the directory.
The name “venv” is a common one, but you can name it whatever you want.
Don’t forget to add this directory to your .gitignore (or equivalent) if you’re using SCM.
Within this newly created directory are the python binaries that we can use to only affect our project. For example, to install pip packages to our environment:
venv/bin/pip install $PackageName
Or to run a python program:
venv/bin/python $ProgramName.py
Activating the environment
If you’re like me and are too lazy to type in the path to the binaries folder every time you want to run a command, then there is the option to activate the environment.
$ source venv/bin/activate
This will change your shell prompt to show you that you’re running python commands from within a venv as well.
Now we can run commands without referencing the binaries folder:
$ pip install $PackageName
Behind the scenes, all this does is change the $PATH entry for the current shell session so that the first entry is the local virtualenv.
$ $PATH
bash: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:
$ source venv/bin/activate
$ $PATH
bash: /path/to/project/dir/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:
To reverse this, either leave the current shell session or run the deactivate script:
$ deactivate
Conclusion
Hopefully this post was short and simple enough to understand, as I expect to refer back to this myself once I inevitably forget how to use virtualenv in a month.
Appendices
References
Virtualenv Official Documentation
A non-magical introduction to Pip and Virtualenv for Python beginners
Versions used
Desktop Machine: kubuntu-18.04.1
Python: Python 2.7.15rc1
Virtualenv: 16.0.0