Python virtual environments

1.0 Python virtual environment

A Python virtual environment comprises a directory tree in which a Python binary, third-party librares, and scripts are installed and isolated from other virtual environments as well—by default—any Python packages installed at the “system” level.

A virtual environment simplifies management of project-level dependencies. A Python project provisioned with a virtual environment can maintain its own set of versioned third-party packages, independent of other projects. A Python virtual environment can also run its own version of Python if created the virtualenv tool.

The Python 3.x standard library includes the venv module for creating virtual environments that are based on the Python binary recognized by your terminal.

1.1 venv module

To create a virtual environment using the venv module issue the following commands from the terminal:

cd path/to/python/project
python3 -m venv /path/to/new/virtual/environment

💡 by convention the virtual environment directory is named “venv”.

After creating the virtual environment, activate it:

macOS/*nix

source venv/bin/activate

Windows 10: venv (Git Bash)

venv/Scripts/activate

Windows 10: venv (cmd.exe)

C:\venv\Scripts\activate

Deactivate the virtual environment by issuing the “deactivate” command:

deactivate

1.2 virtualenv tool

I use the virtualenv tool to create my Python virtual environments. I install it using pip.

❗ Occasionally, Windows users report not being able to run virtualenv. This is likely due to a PATH issue.

macOS: virtualenv

python3 -m pip install virtualenv
cd path/to/project
virtualenv venv
source venv/bin/activate

1.3 Installing packages

Once the virtual environment is created and activated, additional Python packages can be installed and managed in isolation from other projects.

💡 once activated the command prompt will be prefixed with the name of your virtual environment between parentheses.

(venv) . . .

As a test, install the third-party requests package using pip.

macOS

source venv/bin/activate
python3 -m pip install requests
python3 -m pip list

Windows 10

venv/Scripts/activate
python -m pip install requests
python -m pip list

Package    Version
---------- ---------
certifi    2020.12.5
chardet    3.0.4
idna       2.10
pip        20.3.1
requests   2.25.0
setuptools 51.0.0
urllib3    1.26.2
wheel      0.36.1

1.4 requirements.txt file

The requirements.txt file provides a list of required project packages. You can freeze the current set of dependencies and write package and version information to a requirements.txt file using pip.

💡 Whenever you install a new package in the virtual environment remember to update requirements.txt by “freezing” a new version of it.

macOS

python3 -m pip freeze > requirements.txt

Windows 10

python -m pip freeze > requirements.txt

Team members or others who make use of your project code can install all required project dependencies by having pip read requirements.txt and install the listed packages.

macOS

python3 -m pip install -r requirements.txt

Windows 10

python -m pip install -r requirements.txt