QUICK TIP - How to install / connect / freeze a Python Virtual Environment

It is often useful to have one or more Python environments where you can experiment with different combinations of packages without affecting your main installation. Python supports this through virtual environments. The virtual environment is a copy of an existing version of Python with the option to inherit existing packages. A virtual environment is also useful when you need to work on a shared system and do not have permission to install packages as you will be able to install them in the virtual environment.

Outline

• Open a terminal
• Setup the pip package manager
• Install the virtualenv package
• Create the virtual environment
• Activate the virtual environment
• Deactivate the virtual environment
• Optional: Make the virtual environment your default Python
• More: Python virtualenv documentation

Requirements

• An installation of Python

Jargon

Link to Jargon page with terms: terminal

Open a terminal

The method you used to open a terminal depends on your operating system.
Windows
Open the Windows Command Prompt (show path via Start menu and keyboard shortcuts)
Mac OS / Linux
Open the Terminal program. This is usually found under Utilities or Accessories.

Setup the pip package manager

Check to see if your Python installation has pip. Enter the following in your terminal:

If you see the help text for pip then you have pip installed, otherwise download and install pip

Install the virtualenv package

The virtualenv package is required to create virtual environments. You can install it with pip:

Create the virtual environment

To create a virtual environment, you must specify a path. For example to create one in the local directory called ‘mypython’, type the following:

Activate the virtual environment

You can activate the python environment by running the following command:
Mac OS / Linux

Windows

You should see the name of your virtual environment in brackets on your terminal line e.g. (mypython).

Any python commands you use will now work with your virtual environment

Deactivate the virtual environment

To deactivate the virtual environment and use your original Python environment, simply type ‘deactivate’.

Installing packages

Now that you’re in your virtual environment you can install packages. Let’s install the Requests library from the Python Package Index (PyPI):

pip should download requests and all of its dependencies and install them:

 

Installing specific versions

pip allows you to specify which version of a package to install using version specifiers. For example, to install a specific version of requests:

To install the latest 2.x release of requests:

To install pre-release versions of packages, use the --pre flag:

Installing extras

Some packages have optional extras. You can tell pip to install these by specifying the extra in brackets:

Installing from source

pip can install a package directly from source, for example:

Additionally, pip can install packages from source in development mode, meaning that changes to the source directory will immediately affect the installed package without needing to re-install:

Installing from version control systems

pip can install packages directly from their version control system. For example, you can install directly from a git repository:

For more information on supported version control systems and syntax, see pip’s documentation on VCS Support.

Installing from local archives

If you have a local copy of a Distribution Package’s archive (a zip, wheel, or tar file) you can install it directly with pip:

If you have a directory containing archives of multiple packages, you can tell pip to look for packages there and not to use the Python Package Index (PyPI) at all:

This is useful if you are installing packages on a system with limited connectivity or if you want to strictly control the origin of distribution packages.

Using other package indexes

If you want to download packages from a different index than the Python Package Index (PyPI), you can use the --index-url flag:

If you want to allow packages from both the Python Package Index (PyPI) and a separate index, you can use the --extra-index-url flag instead:

Upgrading packages

pip can upgrade packages in-place using the --upgrade flag. For example, to install the latest version of requests and all of its dependencies:

Using requirements files

Instead of installing packages individually, pip allows you to declare all dependencies in a Requirements File. For example you could create a requirements.txt file containing:

And tell pip to install all of the packages in this file using the -r flag:

Freezing dependencies

Pip can export a list of all installed packages and their versions using the freeze command:

Which will output a list of package specifiers such as:

This is useful for creating Requirements Files that can re-create the exact versions of all packages installed in an environment.