Virtual Environments: Why One Environment per Project

Before You Start

You should know: - How to navigate the command line to create and enter folders (mkdir, cd). - How to verify that Python is installed and accessible via your terminal (python --version).

You will learn: - The concept of β€œdependency hell” and why global installations are dangerous. - What a virtual environment mechanically achieves. - How to create, activate, and deactivate a virtual environment using both venv and conda.

Introduction

At this point, you have Python installed on your computer. When you type python in your terminal, the operating system knows exactly which translator to wake up.

It is extremely tempting to just start installing geographic libraries (like numpy, pandas, and geopandas) directly into that single Python installation. This is called a global installation.

Do not do this. Global installations are the single biggest source of frustration for early Python programmers. Eventually, installing packages globally leads to a catastrophic state known as β€œdependency hell.”

To understand why, you need to understand how Python libraries interact.

The Problem: Dependency Conflicts

Imagine you start a project in January called Urban Flooding. You install an advanced fluid dynamics library called WaterSim version 1.0. WaterSim 1.0 is built on top of numpy version 1.18. Python happily installs both geometry libraries for you.

Months later in August, you start a new project called Traffic Network. You install an AI routing library called RoadNet version 3.0. However, RoadNet 3.0 explicitly requires the newest features found in numpy version 1.25. Python dutifully installs numpy 1.25, overwriting your older version.

You finish your Traffic Network project. Months later, a colleague asks about your old Urban Flooding script. You try to run it. It immediately crashes.

Why? Because WaterSim 1.0 was never programmed to interact with numpy 1.25. By upgrading the global dictionary of libraries for your August project, you systematically shattered the architecture of your January project.

The Solution: Virtual Environments

A Virtual Environment is a sandbox. It is an isolated, protective bubble that contains a specific version of Python and a specific dictionary of libraries.

Instead of having one global brain that handles every project, you construct a totally isolated environment for each individual project.

If you have ten different projects on your computer, you should have ten different virtual environments. Project A’s libraries cannot see, touch, or interfere with Project B’s libraries. You can freely upgrade or delete packages in one environment without risk of breaking your older work.

Core Operations

Working with environments involves three key steps: 1. Create the environment (done once per project). 2. Activate the environment (done every time you open a new terminal to work on the project). 3. Deactivate the environment (done when you want to leave the sandbox).

The specific commands depend entirely on which installation pathway you chose in Chapter 4 (Anaconda vs Standard Python).

If you use Standard Python (venv)

First, use your terminal to cd into your project’s folder.

Creation: Instruct Python to generate the environment using the built-in venv module. We typically name the environment folder .venv.

python -m venv .venv

(Mac/Linux users may need to use python3 -m venv .venv). If you run ls now, you’ll see a new folder named .venv sitting in your directory.

Activation: You must actively tell your terminal to step into the sandbox.

On Mac/Linux:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

You will know it worked because your terminal prompt will change, usually placing (.venv) at the far left of the text line.

Deactivation: To leave the sandbox and return to your computer’s global system, simply type:

deactivate

If you use Anaconda / Miniforge (conda)

Conda manages environments centrally rather than scattering them in hidden project folders.

Creation: Instruct conda to create a new environment and explicitly specify the Python version. Let’s call this environment geo-project.

conda create --name geo-project python=3.11

Type y when it asks if you wish to proceed.

Activation: Step into the conda sandbox by running:

conda activate geo-project

Your terminal prompt will change, showing (geo-project) on the left.

Deactivation: To leave the sandbox, type:

conda deactivate

Verify Your Work

Let’s prove the sandbox works.

  1. Step into your project folder (cd).
  2. Create and activate a virtual environment using either venv or conda based on your setup.
  3. Verify your terminal prompt visually indicates you are inside the environment (e.g., (.venv) or (custom-name) appears).
  4. Run the command: python --version.
  5. Run the command deactivate (or conda deactivate).
  6. Observe that the tag disappears from your terminal prompt.

Now that you know how to safely isolate your work spaces, you are ready to start securely pulling down computational libraries out of the internet and into your sandboxes.