Python virtual environments

Python virtual environments are used to compartmentalize the various libraries and versions of things needed for a specific Python project. Libraries can be installed to the OS install of Python, but in doing so that can cause conflicts when different projects need different versions of same library (for example, when one project runs on Django 3.2 and another needs Django 4.2); without virtual environments to separate things, you would need to uninstall+reinstall the library when switching from one project to another.

The venv module is used for creating virtual environments in Python. It will create a folder with a local space for a copy of the python binary and any libraries installed to the virtual environment. It's also common to use "venv" to refer to to the virtual environment itself.

Usage

Creation

python -m venv venv

This is the standard command for creating a venv in a project. It tells Python to use the venv module to create a folder named venv with a virtual environment in it.

Activation

The python binary in the venv (venv/Scripts/python.exe in Windows) can be run directly to use it, but it's often simplest to "activate" the venv such that a given command line session uses the venv instead of the OS-wide Python install automatically.

In VSCode, you can use View -> Command Pallete -> Python: Select Interpreter to tell VSCode which Python to use for that project (the venv will show up in the list alongside the OS-wide Python install). VSCode will generally automatically detect and use the venv when it's created, but it doesn't always do so, so it's sometimes necessary to set (or at least check) that setting.

VSCode Config Note

VSCode previously prepended (venv) to the command prompt when the venv is being used, that seemed to stop at some point. This block of config in the proper VSCode settings JSON file for the OS or workspace seems to fix that (not 100% sure how it works, but it seems to). This is an entirely optional thing, the venv can still be active without it, it's simply sometimes useful as a visualization.

"terminal.integrated.profiles.windows": {
    "PowerShell": {
        "source": "PowerShell",
        "icon": "terminal-powershell"
    },
    "Command Prompt": {
        "path": [
            "${env:windir}\\Sysnative\\cmd.exe",
            "${env:windir}\\System32\\cmd.exe"
        ],
        "args": [],
        "icon": "terminal-cmd"
    },
    "Git Bash": {
        "source": "Git Bash"
    }
},

It's also possible to manually activate the venv manually in a command prompt, using venv/Scripts/activate.bat, but that's something you should never need to do manually with VSCode properly configured.

Dependency installation

Once the venv is created and activated, the following command can be used to install the dependencies for a given project. This is necessary during the initial setup process and also sometimes due to code changes.

pip install -r requirements.txt

Errors when installing CGIT libraries

Sometimes you'll see an error when trying to install on of the CGIT Python libraries hosted on GitLab. The fix is generally to update pip with the following command and then try installing the requirements again.

python -m pip install --upgrade pip