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:
- Creating new environments
- Use and management
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 Environments
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 &amp; 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):
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
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
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
--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:
pip==9.0.1 setuptools==36.2.1 wheel==0.29.0
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
-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.
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
pyperclip==1.5.27 selenium==3.4.3 splinter==0.7.5
Now, lets create a new virtual environment called
new_venv. Once this new environment is created, we can try importing the
$ 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:
- Package installation
- Exporting environment requirements
- Importing environment requirements
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.