Setting Up Your Environment

Getting your computer ready for notebooks, code, GIS, and lab work on Windows, macOS, Linux, and Raspberry Pi

This book is designed so that much of the learning can happen directly on the page. You can read, think, and often experiment without needing a complicated local setup.

But some of the labs and companion projects work better when you have your own environment ready:

The good news is that your setup does not need to be fancy. It needs to be stable, understandable, and easy to recover when something goes wrong.

What You Actually Need

For most readers, a good starter environment includes:

If you want to go further into spatial labs, it is also useful to have:

A Good Rule

Do not install everything globally if you can avoid it.

Instead, aim for:

This makes it much easier to fix problems later.

If you want the short version, this is the recommended starter stack:

That stack is not the only good one. It is simply a practical one with lots of documentation and low friction for beginners.

Windows

Windows is perfectly usable for this work, but it helps to be deliberate.

  1. Install VS Code
  2. Install Git for Windows
  3. Install Python 3 from the official Python site
  4. Make sure Python is added to PATH
  5. Install JupyterLab
  6. Optionally install QGIS

Terminal choices

You can use:

Recommended:

That gives a cleaner and more modern experience.

Check that Python works

Open a terminal and run:

python --version

or, on some Windows systems:

py --version

If that prints a Python version, your install is visible.

Create a virtual environment

Inside a project folder:

python -m venv .venv

Activate it in PowerShell:

.\.venv\Scripts\Activate.ps1

Then install JupyterLab:

python -m pip install jupyterlab

Windows caution

Beginners often run into problems because:

If things get messy, a clean reinstall plus a fresh virtual environment is often faster than debugging for hours.

macOS

macOS is usually a smooth platform for this kind of work.

  1. Install VS Code
  2. Install Homebrew
  3. Install Git if it is not already present
  4. Install Python 3
  5. Install JupyterLab
  6. Optionally install QGIS

Check for Git

In the terminal:

git --version

If Git is not installed, macOS may prompt you to install command-line developer tools.

Check for Python

Use:

python3 --version

On macOS, python3 is usually safer than python.

Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install jupyterlab

macOS caution

Do not depend on the old system Python for learning projects.

It is better to use your own Python installation and your own project environments.

Linux

Linux is often the easiest platform for reproducible scientific and technical work, especially if you become comfortable with the terminal.

  1. Install VS Code or another editor you like
  2. Make sure git is installed
  3. Install python3
  4. Install python3-venv
  5. Install pip
  6. Install JupyterLab
  7. Optionally install QGIS

Example package install

On Debian or Ubuntu style systems:

sudo apt update
sudo apt install python3 python3-venv python3-pip git

Then, in your project folder:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install jupyterlab

Linux caution

Package names and install commands vary across distributions. The general pattern matters more than memorizing one exact command.

You want:

Raspberry Pi

The Raspberry Pi deserves special attention because it is such a good learning machine.

It is inexpensive, tangible, and excellent for teaching the idea that computing environments are built, not magical.

It is also more resource-constrained than a laptop or desktop, so your setup choices matter more.

Good use cases for Raspberry Pi

A Pi is great for:

It is less ideal for:

  1. Use a current Raspberry Pi OS
  2. Update the system
  3. Install Python tools, Git, and Jupyter
  4. Use lightweight projects first
  5. Keep storage and memory limits in mind

Example:

sudo apt update
sudo apt upgrade -y
sudo apt install python3 python3-venv python3-pip git

Then:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install jupyterlab

Raspberry Pi tips

When to move from Pi to a larger machine

Move to a laptop, desktop, or remote server when:

That is not failure. It just means the scale of the problem has changed.

Folder Structure

A simple project structure helps a lot.

For example:

geography-work/
├── notes/
├── labs/
│   ├── lab-01/
│   ├── lab-02/
│   └── ...
├── data/
└── scratch/

Within a single lab:

lab-01/
├── README.md
├── notebooks/
├── data/
├── outputs/
└── .venv/

This is not the only good structure, but it helps you separate:

What To Install First

If you are trying not to overwhelm yourself, install in this order:

  1. browser
  2. code editor
  3. Python
  4. Git
  5. virtual environment support
  6. JupyterLab
  7. optional GIS tools

That is enough to begin.

Sanity Check

Before starting labs, make sure you can do all of these:

python --version
git --version

or on systems where needed:

python3 --version
git --version

Then try:

python -m pip --version

and:

jupyter lab

If those work, you are in good shape.

If This Gets Hard, Focus On

A clean, boring setup is better than an advanced, confusing one.

If you want the shortest possible answer:

That is enough to start almost all of the companion lab work successfully.