Creating a Python Virtual Environment

When you are writing new software programs, it’s possible (and common!) to modify dependencies and environment variables that your other software depends on. This can cause many problems, so should be avoided. A Python virtual environment solves this problem by wrapping all the dependencies and environment variables that your new software needs into a filesystem separate from the rest of the software on your computer.

The virtual environment tool in Python is called venv, but before we set up venv, we need to create our club site project folder.

Create a Project Folder

Our project folder will house not only our virtual environment, but all the code and media for our Django club site.

The project folder can go anywhere on your computer, although it’s highly recommended you create it somewhere in your user directory, so you don’t get permission issues later on. A good place for your project in Windows is your My Documents folder. On a Mac your Documents folder is also a logical choice; however, it can go anywhere in your user directory.

Create a new folder on your system. I have named the folder myclub_project, but you can give the folder any name that makes sense to you.

For the next step, you need to be in a command window (terminal on Linux and macOS). The easiest way to do this in Windows is to open Windows Explorer, hold the SHIFT key and right-click the folder to get the context menu and click on Open command window here (Figure 2-5).

Figure 2.5: Hold the shift key and right-click a folder to open a command window.

Terminal in Windows 10

If you are running newer versions of Windows 10, the command prompt has been replaced by PowerShell. For the examples in this book, the command prompt and PowerShell are functionally the same, and all commands will run in PowerShell unmodified.

Create a Python Virtual Environment

Once you have created your project folder, you need to create a virtual environment for your project by typing the following at the command prompt you just opened:

On Windows

...\Documents\myclub_project> python -m venv env_myclub

On Mac

...$ python3 -m venv env_myclub

Remember, you must be inside the project folder!

The function of this command is straightforward—the -m option tells Python to run the venv module as a script. venv in turn requires one parameter: the name of the virtual environment to be created. So this command is saying “create a new Python virtual environment and call it env_myclub”

Once venv has finished setting up your new virtual environment, it will switch to an empty command prompt. When it’s done, open Windows Explorer and have a look at what venv created for you. In your project folder, you will now see a folder called \env_myclub (or whatever name you gave the virtual environment). If you open the folder on Windows, you will see the following:

\Include 
\Lib 
\Scripts
pyvenv.cfg

On a Mac, it’s:

/bin
/Include 
/Lib
pyvenv.cfg

On either platform, if you look inside the \Lib folder, you will see venv has created a complete Python installation for you, separate from your other software, so you can work on your project without affecting other software on your system.

To use this new Python virtual environment, we have to activate it, so let’s go back to the command prompt and type the following:

On Windows

env_myclub\scripts\activate

On Mac

source env_myclub/bin/activate

This will run the activate script inside your virtual environment’s \scripts folder. You will notice your command prompt has now changed:

(env_myclub) ...\Documents\myclub_project>

On a Mac, the prompt looks like this:

(env_myclub) ... <yourusername>$

The (env_myclub) at the beginning of the command prompt lets you know that you are running in the virtual environment.

Oops! Script Error!

If you are using PowerShell and running this script for the first time, the activate command will throw a permission error.

If this happens to you, open PowerShell as an administrator and run the command:

Set-ExecutionPolicy remoteSigned

Once you have run this command, the activation script will run.

If you want to exit the virtual environment, you just type deactivate at the command prompt:

(env_myclub) ...\Documents\myclub_project> deactivate
...\Documents\myclub_project>