Setting up a Python virtual environment

In this section, we will discuss how Python interacts with your operating system installation and cover the steps necessary to set up and configure a Python development environment. In addition, as part of our setup process, we will clone the GitHub repository that contains all of the code (organized by chapter) for this book.

By default, Python and its package management tool, pip, operate globally at the system level and can create some confusion for Python beginners because this global default is in contrast to many other language ecosystems that operate locally on a project folder level by default. Unwearyingly working and making changes to the global Python environment can break Python-based system-level tools, and remedying the situation can become a major headache.

As a Python developer, we use Python virtual environments to sandbox our Python projects so they will not adversely interfere with system-level Python utilities or other Python projects.

In this book, we will be using a virtual environment tool known as venv, which comes bundled as a built-in module with Python 3.3 and above. There are other virtual environment tools around, all with their relative strengths and weaknesses, but they all share the common goal of keeping Python dependencies isolated to a project.

virtualenv and pipenv are two alternative virtual environment tool options that offer more features than venv. These alternatives are well suited for complex Python projects and deployments. You'll find links to these in the Further reading section at the end of this chapter.

Let's begin and clone the GitHub repository and create a new Python virtual environment for this chapter's source code. Open a new Terminal window and work through the following steps:

1. Change into or create a folder where you want to store this book's source code and execute the following commands. With the last command, we rename the cloned folder to be pyiot. This has been done to help shorten Terminal command examples throughout the book:

$ cd ~
$ git clone https://github.com/PacktPublishing/Practical-Python-Programming-for-IoT
$ mv Practical-Python-Programming-for-IoT pyiot

2. Next, change into the chapter01 folder, which contains the code relating to this chapter:

$ cd ~/pyiot/chapter01

3. Execute the following command, which creates a new Python virtual environment using the venv tool. It's important that you type python3 (with the 3) and remember that venv is only available with Python 3.3 and above:

$ python3 -m venv venv

The options that we are passing to python3 include -m venv, which tells the Python interpreter that we want to run the module named venv. The venv parameter is the name of the folder where your virtual environment will be created.

While it might look confusing at first glance in the preceding command, it's a common convention to name a virtual environment's folder venv. Later in this chapter, in the Anatomy of a virtual environment section, we will explore what lies beneath the venv folder we just created.

4. To use a Python virtual environment, we must activate it, which is accomplished with the activate command:

# From with in the folder ~/pyiot/chapter01
$ source venv/bin/activate
(venv) $

When your Terminal has a Python virtual environment activated, all Python-related activity is sandboxed to your virtual environment.

Notice in the preceding code that, after activation, the name of the virtual environment, venv, is shown as part of the Terminal prompt text, that is, (venv) $. In this book, whenever you see Terminal examples where the prompt is (venv) $, it's a reminder that commands need to be executed from within an activated Python virtual environment.

5. Next, execute which python (without the 3) in your Terminal, and notice that the location of the Python executable is beneath your venv folder and if you check the version of Python, it's Python version 3:

(venv) $ which python
/home/pi/pyiot/chapter01/venv/bin/python

(venv) $ python --version
Python 3.7.3

6. To leave an activated virtual environment, use the deactivate command as illustrated here:

(venv) $ deactivate
$ 

Notice also that (venv) $ is no longer part of the Terminal prompt text once the virtual environment has been deactivated.

Remember to type deactivate to leave a virtual environment, not exit. If you type exit in a virtual environment, it will exit the Terminal.

7. Finally, now that you are outside of our Python virtual environment if you execute which python (without the 3) and python --version again, notice we're back to the default system-level Python interpreter, which is version 2:

$ which python
/usr/bin/python

$ python --version
Python 2.7.13

As we just illustrated in the preceding examples, when we ran python --version in an activated virtual environment, we see that it's Python version 3 whereas in the last example, at the start of this chapter, the system level, python --version, was version 2, and we needed to type python3 --version for version 3. In practice, python (with no number) relates to the default version of Python. Globally, this is version 2. In your virtual environment, we only have one version of Python, which is version 3, so it becomes the default.

A virtual environment created with venv inherits (via a symbolic link) the global Python interpreter version that it was invoked with (in our case, version 3 because the command was python3 -m venv venv). If you ever need to target a specific Python version that is different from the global version, investigate the virtualenv and pipenv virtual environment alternatives.

We have now seen how to create, activate, and deactivate a Python virtual environment and why it is important to use a virtual environment to sandbox Python projects. This sandboxing means we can isolate our own Python projects and their library dependencies from one another, and it prevents us from potentially disrupting the system-level installation of Python and breaking any system-level tools and utilities that rely on them.

Next, we will see how to install and manage Python packages in a virtual environment using pip.