Virtual Environments Pt. 2A – Virtualenv

This is Part 2A of my series on virtual environments, which covers virtualenv, a Python specific package for managing virtual environments. If you are new to virtual environments, I suggest checking out Part 1 of the series, which covers virtual environment basics.  This guide will cover how to do the following with the virtualenv package:

  1. Installation
  2. Creating new environments
  3. Use and management
  4. Exporting
  5. Importing

This guide ends with a comprehensive example that incorporates most of the steps covered in the article.  Note that the version numbers you see locally may differ from my own; this is normal.  Different versions of python and pip may download different package versions.


virtualenv is a widely used virtual environment manager for Python.  The latest stable package can be installed through pip via:

$ pip install virtualenv

Creating New 

Creating a new virtual environment is a simple process.  Open a blank folder in the directory of your choosing and enter the following:

$ virtualenv my_venv

Using this command will create a new folder called my_venv which contains everything needed to run an isolated version of python.  Virtual environment name restrictions following standard file/directory name restrictions.  The word venv is usually used as a suffix for the environment name to clearly indicate purpose.

Using and Managing Current Environments

Virtual environments must be activated before use.  The method for activating virtual environments differs slightly depending on which OS you are using:

$ source my_venv/bin/activate #Linux & Mac
$ my_venv\Scripts\activate #Windows

Note the differences between slash direction, path, and whether or not the source keyword is used.

Activating will alter your command line by inserting (my_venv) to the left of the line itself.  Below are examples of an activated virtual environment for terminal and windows command prompt.

(my_venv) jhart@home$  #Linux $ Mac terminal
(my_venv) C:\Users\jhart #Windows cmd prompt

You can continue to use the terminal normally during this time.  You can deactivate the environment using the following command (same for all operating systems):

$ deactivate

Note that closing the terminal will also deactivate it.

While your virtual environment is active, pip can still be used to install packages.  The packages installed will match versions compatible with whatever version of Python is installed to the activated environment.  All installed packages to the are contained to the your virtual environment’s folder.

Deleting the environment doesn’t require any command at all; simply delete the folder created by the virtualenv command.

Custom Python Version

By default, your virtual environment’s python interpreter is the same version as your main python interpreter.  To change this, you can do the following:

$ virtualenv my_venv -python=python2.7

-python=python2.7 will result in python 2.7 being installed.  You main python install won’t be affected in any way, and any version of Python can be installed to a virtual environment.


Importing and exporting virtualenv environment is done through pip, not virtualenv.
To export a virtual environment, activate the environment of interest and enter the following into the terminal:

$ pip freeze > requirements.txt

This will create a text document called requirements in whatever directory the terminal is currently active in.  The file name isn’t limited to “requirements”, but it should be something descriptive if it will be shared with others.  The only stipulation is that it must be a .txt file.

If my_venv was the active virtual environment during the export process, this would create a blank document because only the default packages ( pip, setuptools, and wheel) were installed to it during initial generation process.  To output all installed packages, including the three defaults, enter the following:

$ pip freeze > requirements.txt --all

The --all flag tells pip to also include pip, setuptools, and wheel in addition to all other installed packages.  Executing that command locally gives me a document with the following:



Importing Requirements

The setup for importing a requirements file matches that of exporting a requirements file.  Activate the target virtual environment and enter the following:

$ pip install -r requirements.txt

The -r flag in the above command tells pip to install the requirements listed in the file requirements.txt.  Anything listed in that file will be installed via pip to the active environment.  If no environment is activated, pip will install everything yto your main Python environment.

You can read more about pip freeze here.

Comprehensive Example

To wrap up virtualenv, lets make another virtual environment, and use a new requirements.txt file from my_venv as the basis.   Before creating a new environment, lets install some actual python packages to my_venv prior to the export process.

$ source my_venv/bin/activate   #Linux activation method
$ pip install Splinter          #Install Splinter package
$ pip install pyperclip         #Install pyperclip package
$ pip freeze > requirements.txt #Export package requirements
$ deactivate                    #Deactivate environment

If there were no errors, requirements.txt should contain the following


Now, lets create a new virtual environment called new_venv. Once this new environment is created, we can try importing the  requirements.txt file.

$ virtualenv new_venv               #Create new environment
$ source new_venv/bin/activate      #Linux activation method
$ pip install -r requirements.txt   #Install package requirements
$ pip list                          #List installed packages

If the import process was successful, pip list should output the following:

pip (9.0.1)
pyperclip (1.5.27)
selenium (3.4.3)
setuptools (36.2.1)
splinter (0.7.5)
wheel (0.29.0)

Performing all these steps accomplishes the following tasks, all of which make up fundamental virtual environment management practices:

  1. Creation
  2. Activation
  3. Package installation
  4. Exporting environment requirements
  5. Importing environment requirements

Wrapping Up

If you are interested in alternative method of implementing virtual enviroments, you can check out Part 2B (upcomming), which covers the conda utility.  Unlike virtualenv and pip, which are limited to Python, conda can be used by any programming language.

2 thoughts on “Virtual Environments Pt. 2A – Virtualenv

  1. Pingback: Virtual Environments Pt. 1 – An Overview | The Uncertain Programmer

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s