Wayward·House

Essays System Signals Library Topics About 🐾 Ask Pepper

Installing Python: Miniforge vs. Standard Python

Before You Start

You should know: - How to navigate the command line using ls, pwd, and cd. - The basic difference between an operating system and software installed on it.

You will learn: - Why there are two main ways to install Python and which one to choose. - How to install Python on your specific operating system. - How to verify that your terminal can actually find the installation. - How to handle the Python 2 remnant that still ships on many Macs.

Introduction

Python is not a program you open by double-clicking a desktop icon. It is a language interpreter — a translator that reads your .py text files and executes them as machine instructions. To use it, you must install this interpreter on your computer and make sure your terminal knows where to find it.

In scientific computing, installing “just Python” is rarely sufficient. You also need specialized libraries — NumPy, SciPy, GDAL — that depend on compiled C and Fortran code. Because these are notoriously hard to build from source, the community has developed two distinct philosophies for managing Python installations. Choosing the right one now saves many hours of troubleshooting later.

Path 1: Miniforge (Recommended for Geographic Work)

Miniforge is a minimal installer for the conda package manager, pre-configured to pull from conda-forge — a community channel that maintains pre-compiled binaries for complex geographic libraries.

When you install Miniforge, you get Python, the conda package manager, and nothing else. You install everything else as needed, into isolated environments (covered in the next chapter).

Why Miniforge beats full Anaconda: Full Anaconda installs 4–5 GB of packages you probably don’t need. Miniforge installs in minutes and gives you the same conda tool without the bloat.

Why conda matters for geography: Libraries like GDAL, rasterio, fiona, and pyproj require compiled C code. On Windows especially, pip install rasterio frequently fails with confusing compiler errors. conda install rasterio works because conda distributes pre-compiled binaries.

Choose Miniforge if: You are on Windows, or you plan to do heavy geospatial work (raster processing, shapefiles, coordinate system transformations). This is the recommended path for this book.

How to Install Miniforge

1. Go to the Miniforge releases page.
2. Download the installer for your OS:
   • Windows: Miniforge3-Windows-x86_64.exe
   • macOS (Apple Silicon): Miniforge3-MacOSX-arm64.sh
   • macOS (Intel): Miniforge3-MacOSX-x86_64.sh
   • Linux: Miniforge3-Linux-x86_64.sh
3. Run the installer:

   • Windows: Double-click the .exe. Accept defaults. On the “Advanced Options” screen, leave “Add to PATH” unchecked (Miniforge manages this its own way).

   • macOS/Linux: Open a terminal, navigate to your Downloads folder, and run:

     bash Miniforge3-MacOSX-arm64.sh

     (Replace the filename with whichever you downloaded.) Follow the prompts. When asked if you want conda to initialize your shell, say yes.

4. Close your terminal completely and open a new one. This is essential — terminals load their configuration at startup, and the installer has just modified that configuration.

Path 2: Standard Python + pip (The Lightweight Option)

If you prefer a minimal, fast installation and your work leans toward data analysis rather than heavy geospatial processing, standard Python from python.org is a perfectly good choice. It comes with pip, the standard package installer.

Choose standard Python if: You are on macOS or Linux and your work focuses on data analysis, visualization, and scripting rather than raster processing or projection transformations.

How to Install (Windows)

Download the installer from python.org/downloads. On the very first screen, check the box labelled “Add Python to PATH” before clicking Install. This is the single most common mistake — if you forget it, your terminal will never find Python.

How to Install (macOS)

Macs ship with a system Python that you should never touch. Install a user-controlled Python instead using Homebrew:

# Install Homebrew first (paste this in your terminal)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Then install Python
brew install python

How to Install (Linux)

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

Verifying Your Installation

Close your terminal completely and open a new one. This is not optional — terminals load path settings at startup. If you skip this step, your terminal will still be looking in the old places.

Now type:

python --version

If Python was found, you will see something like:

Python 3.11.4

If you are on macOS and see Python 2.7.x: This is the old system Python that ships with macOS. It is not the one you just installed. Try python3 --version instead. If that returns 3.x, you are fine — just use python3 wherever these instructions say python. (Python 2 was officially retired in 2020 and should not be used for new work.)

If you get command not found: Your terminal cannot locate the Python executable. On Windows, this means you forgot to check “Add to PATH” during installation — uninstall and reinstall with that box checked. On macOS with Miniforge, make sure you said yes when the installer asked about initializing your shell, then fully close and reopen the terminal.

If you are on Windows and get the Microsoft Store: Windows intercepts the python command and offers to install Python through the Store. Cancel this, uninstall any Store version, and reinstall using the official installer with the PATH checkbox ticked.

Verifying Miniforge Specifically

If you installed Miniforge, also verify that conda is accessible:

conda --version

You should see something like conda 23.5.0. If this works, conda can find its environment store and you are ready to create environments in the next chapter.

Verify Your Work

1. Close all terminals and open a fresh one.
2. Run python --version (or python3 --version on macOS/Linux).
3. Confirm the version number starts with 3. — not 2..
4. If you installed Miniforge, run conda --version as well.

Do not proceed to the next chapter until your terminal can print a Python 3 version number. Every chapter from here on depends on it.

Next Steps

• Proceed to Virtual Environments: Why One Environment per Project