Using virtual environments

The Python Standard Library contains the module venv, which creates virtual environments. It uses the Python interpreter, whose venv module is called.

In comparison to the third-party library virtualenv, the virtual environment is not completely independent from its base interpreter. That means, the environment becomes unusable, if the base interpreter is uninstalled, but also that the virtual environment is updated to later versions, if the base interpreter is (for example, 3.9.2 -> 3.9.3).

Some commands below expect that your virtual environments are located in %USERPROFILE%/.venv (Windows) and $HOME/.venv (Linux / macOS). You may choose any other directory, but make sure to adapt the commands.

Create a virtual environment

$ python -m venv </path/to/target/env>

Hint

On Windows, it has been observed, that if the interpreter is not referenced by python but something like python3.9, the command fails. In that case, use the absolute path to your interpreter, for example:

C:\> C:\Users\my_username\AppData\Local\Programs\Python\Python39\python.exe -m venv </path/to/target/env>

You may choose something like ~/.venv/my_project_venv (Windows: %USERPROFILE%\.venv\my_project_env) as target path.

Activate the virtual environment

On Linux / macOS:

$ source </path/to/target/env>/bin/activate

On Windows:

C:\> </path/to/target/env>/Scripts/activate.bat

Add activation script to your project

To easily activate the associated environment from inside a project, create a file called activate (Windows: activate.bat) in your project’s root directory.

On Linux / macOS:

$ cd /my/project/root
$ touch activate
$ chmod a+x activate

Next, open the activate script and add the following content, then save exit:

#!/usr/bin/env bash

source ~/.venv/<ENV_NAME>/bin/activate

Make the script executable via chmod u+x activate. To call the script, run:

$ source activate

# or alternatively
$ . activate

Hint

Starting the script without source will execute the command in a sub-shell, in which case the environment is activate only for the sub-shell, which is closed, once the script finished.

On Windows:

Create the file activate.bat inside the project’s root directory. Open it and add the following content:

@echo off

call %USERPROFILE%\.venv\<ENV_NAME>\Scripts\activate

Windows: Activate your environments from anywhere

It may be useful to activate an environment from anywhere and also to get an overview over your virtual environments.

On Windows:

Save the following content into a file called activate.bat. The file must be saved in a directory, which is listed the PATH environmental variable (for example, create a directory C:\bin):

@echo off

set ENV=%1
set AVAILABLE_ENV=dir %USERPROFILE%\.venv /A:D /B

if [%ENV%]==[] (
    echo:
    echo Missing environment name.
    echo:
    echo Usage: activate ^<ENV_NAME^>
    GOTO INVALID_INPUT
)

%AVAILABLE_ENV%|find "%ENV%" > nul

if errorlevel 1 (
    echo:
    echo Environment '%ENV%' was not found.
    GOTO INVALID_INPUT
) else (
    %USERPROFILE%\.venv\%ENV%\Scripts\activate.bat
    GOTO EOF
)

:INVALID_INPUT
echo:
echo Possible selections
echo -------------------
%AVAILABLE_ENV%

:EOF
exit /b 0

Hint

The script expects all virtual environments to be available in C:\Users\<YOUR_USERNAME>\.venv. If not, adapt the script accordingly.

To run the script, run activate <ENV_NAME> from anywhere. To see all available environments only run activate.