trying to figure out how to get codespaces and gdal to be happy

Author: MattReimer

.devcontainer/bootstrap.sh

@@ -4,4 +4,11 @@ wget https://raw.githubusercontent.com/Riverscapes/environment/master/nar-ys.zsh
 wget https://raw.githubusercontent.com/Riverscapes/environment/master/.aliases -O ~/.aliases
 wget https://raw.githubusercontent.com/Riverscapes/environment/master/.zshrc -O ~/.zshrc
 
-uv sync
+uv sync
+
+# Install system GDAL and the matching Python gdal package.
+# The Python gdal version must match the system libgdal version, so it cannot
+# be pinned in pyproject.toml generically. We install it here explicitly.
+sudo apt-get update
+sudo apt-get install -y --no-install-recommends libgdal-dev gdal-bin
+bash install_geo.sh

.devcontainer/devcontainer.json

@@ -3,7 +3,7 @@
 {
 	"name": "Data Excahnge Scripts",
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
 	"features": {
 		"ghcr.io/va-h/devcontainers-features/uv:1": {}
 	},

README.md

@@ -63,27 +63,41 @@ Running scripts this way will also allow you to drop breakpoints in your code an
 
 ## Optional Dependencies
 
-This project includes optional dependencies for geospatial functionality. To install these dependencies, run:
+This project includes optional dependencies for geospatial functionality (e.g. `shapely`). Install them with:
 
 ```bash
 uv sync --extra geo
 ```
 
-This will install packages like `gdal` and `shapely`. Note that `gdal` may require additional system-level dependencies. On macOS, you can install `gdal` using Homebrew:
+### GDAL
 
+`gdal` is **not** pinned in `pyproject.toml` because the Python package version must exactly match the system `libgdal` version, which varies per environment. Instead, use the provided helper script after installing system GDAL:
+
+**Debian/Ubuntu (including Codespaces — requires Debian Bookworm / Ubuntu 22.04+ for Python 3.12 compatibility):**
+```bash
+sudo apt-get install -y libgdal-dev gdal-bin
+bash install_geo.sh
+```
+
+> **Note:** Debian Bullseye (11) ships GDAL 3.2, which is incompatible with Python 3.12. The devcontainer uses Debian Bookworm (12) which provides GDAL 3.6+.
+
+**macOS:**
 ```bash
 brew install gdal
+bash install_geo.sh
 ```
 
+The `install_geo.sh` script calls `gdal-config --version` to detect the installed system GDAL version and installs the exactly matching `gdal` Python package into the active virtual environment.
+
 ## Codespace Instructions
 
 1. Open the codespace "Riverscapes API Codespace."
 2. In VSCode, load the `RiverscapesAPI.code-workspace` workspace.
 3. Ensure the appropriate Python version is selected (e.g., `3.12.9 ('.venv')`).
 
-### Codespace GDAL Limitation
+### Codespace GDAL
 
-> NOTE: The codespace environment does not currently support scripts requiring GDAL (e.g. project merging). Run those locally.
+GDAL is installed automatically when the codespace is created (via `bootstrap.sh`). No extra steps needed — `gdal-config` will be available and `install_geo.sh` will have already run.
 
 ## Best Practices
 

install_geo.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Installs the GDAL Python package matching the currently installed system GDAL.
+#
+# Usage:
+#   bash install_geo.sh
+#
+# Prerequisites (run once per machine/codespace before this script):
+#   Debian/Ubuntu:  sudo apt-get install -y libgdal-dev gdal-bin
+#   macOS:          brew install gdal
+#   Windows:        install OSGeo4W or download GDAL binaries from https://www.gisinternals.com/
+
+set -euo pipefail
+
+if ! command -v gdal-config &>/dev/null; then
+    echo "ERROR: gdal-config not found."
+    echo "Please install the system GDAL development libraries first:"
+    echo "  Debian/Ubuntu: sudo apt-get install -y libgdal-dev gdal-bin"
+    echo "  macOS:         brew install gdal"
+    exit 1
+fi
+
+GDAL_VERSION=$(gdal-config --version)
+echo "System GDAL version: ${GDAL_VERSION}"
+
+# GDAL < 3.3 Python bindings use the deprecated 'use_2to3' setuptools feature,
+# which was removed in setuptools 58+ and is incompatible with Python 3.12.
+MAJOR=$(echo "${GDAL_VERSION}" | cut -d. -f1)
+MINOR=$(echo "${GDAL_VERSION}" | cut -d. -f2)
+if [[ "${MAJOR}" -lt 3 ]] || [[ "${MAJOR}" -eq 3 && "${MINOR}" -lt 3 ]]; then
+    echo "ERROR: System GDAL ${GDAL_VERSION} is too old. Python 3.12 requires GDAL >= 3.3."
+    echo "Debian Bullseye only ships GDAL 3.2 — upgrade to Debian Bookworm (or use a"
+    echo "newer apt source) to get a compatible GDAL version."
+    exit 1
+fi
+
+echo "Installing Python gdal==${GDAL_VERSION} into the current environment..."
+uv pip install "gdal==${GDAL_VERSION}"
+
+echo "Done. GDAL Python package installed successfully."

pyproject.toml

@@ -38,9 +38,11 @@ dependencies = [
 
 [project.optional-dependencies]
 geo = [
-  "gdal==3.11.4",
   "shapely>=2.1.1",
 ]
+# NOTE: gdal is intentionally excluded from the geo extra because the Python
+# gdal package version must exactly match the system libgdal version, which
+# varies per developer environment. Use `install_geo.sh` to install gdal.
 
 [tool.setuptools]
 include-package-data = true