Python Virtual Environment

External

• https://peps.python.org/pep-0405/ PEP 405 – Python Virtual Environments

Internal

• Python Language
• Calling Python from bash
• Poetry

Overview

A virtual environment is a mechanism to isolate a set of installed dependencies. Virtual environments can be managed with tools like virtualenv, venv, Poetry, etc. and reside in directories called venv or .venv within the project's root, or, as in the case for Poetry, in other locations. It is a good practice to avoid storing the content of venv or equivalent in source control. The content is populated locally on the developers' machines.

Virtual Environment Contents

A virtual environment contains a relatively large number of files (thousands).

What exactly does it contain? Does it contain a fully independent Python interpreter copy?

Virtual Environment Creation

A virtual environment can be created manually as follows:

python -m venv <virtual-env-dir-name>

Example:

python -m venv .venv

The command creates a virtual Python environment in the specified target directory, and installs the same Python version it is run with. By default, the Python binaries are linked from within .venv/bin directory. This is fine if the virtual environment is accessed from the system it was created, but it leads to broken links if the virtual environment is accessed from a different system. For more details on symbolic links versus copies, see "Symbolic Link and Copies" below. The command also installs pip. More more details on virtual environments and pip see "Virtual Environments and pip" below.

Symbolic Links and Copies

When the virtual environment is created, the default behavior is to link the Python binaries from .venv/bin to the system installation. This is fine if the virtual environment is always accessed from the same system, but it will lead to broken symbolic links if the virtual environment is serialized and accessed from a different system.

To ensure that the binaries are physically copied, use the --copies argument:

python -m venv --copies <virtual-env-dir-name>

This will affect the following files:

.venv
  ├─ bin
      ├─
      ├─ python 
      ├─ python3
      ├─ python3.10
      ...

Another important aspect when using copies is to make sure the executable format of the binary file matches the image the virtual environment is accessed from: a virtual environment built on Mac will not work on a Linux image.

Virtual Environments and pip

The venv module installs pip as part of the virtual environment creation. After the virtual environment is created, it is usually a good idea to upgrade pip:

.venv/bin/python -m pip install --upgrade pip

The dependencies can then be installed with:

.venv/bin/pip install -r requirements.txt

For more details on virtual environments and dependencies see Virtual Environments and Dependencies below.

Upgrade pip for an Already Initialized Virtual Environment

To upgrade pip within an already initialized virtual environment:

venv/bin/python -m pip install --upgrade pip

Virtual Environments and Dependencies

Individual Dependencies

./venv/bin/pip install numpy

requirements.txt Dependencies

The dependencies can then be installed with:

venv/bin/pip install -r requirements.txt

TO TEST THAT: The dependencies installed in a virtual environment are used automatically if the interpreter is ./venv/bin/python.

Also see:

pip

requirements.txt

Bash Wrapper that Bootstraps a Virtual Environment

Calling Python from bash | bash Wrapper that Bootstraps a Virtual Environment

Activated Virtual Environment Shell

An "activated" virtual environment means making the virtual environment Python interpreter the default interpreter for the shell session.

To activate the virtual environment:

source .venv/bin/activate

To "deactivate", run:

deactivate

or simply exit the shell.