GeoAI (geoai-py): a Python layer for training and running geospatial models

The gap geoai-py is trying to fill

Geospatial deep learning usually means assembling three things: a model library, a data loader that understands coordinate reference systems and tiling, and a way to get imagery. The README states the project's own view of this problem directly, describing existing solutions as requiring researchers to navigate fragmented ecosystems of tools, and naming TorchGeo, TerraTorch and SRAI as strong foundational libraries that still leave a gap for high-level interfaces. That is an honest framing of the target audience: geospatial researchers who need AI workflows without deep machine learning expertise, AI practitioners who want the preprocessing done, and educators who need reproducible examples. If you already write PyTorch training loops comfortably, you are not the primary user. The package is a convenience layer, and convenience layers cost you control over the details.

What actually sits inside the package

The README lists six capabilities: search and download of remote sensing imagery and geospatial data, automated dataset preparation with image chips and label generation, model training for classification, detection and segmentation, inference pipelines, interactive visualization through Leafmap and MapLibre, and a QGIS plugin. The underlying stack is PyTorch, Hugging Face Transformers, segmentation_models.pytorch and torchange. Two structural facts matter more than the feature list. First, pyproject.toml declares a console entry point, geoai = "geoai.cli:main", so there is a command line interface in addition to the Python API. Second, the repository root contains geoai-mcp-server/ and agent-harness/ directories alongside qgis_plugin/, which tells you the project is being extended in several directions at once rather than staying a single-import library. Supported formats named in the README are GeoTIFF, JPEG2000, GeoJSON, Shapefile and GeoPackage, and the package claims automatic device management for GPU acceleration when available.

Installing geoai-py and running a first task

The distribution name on PyPI is geoai-py, while the import name and the conda-forge package are both geoai. The README does not spell out a pip command, but the badge links point at pypi.org/project/geoai-py and anaconda.org/conda-forge/geoai, so those are the two channels. The conda route is the safer one, because the dependency list in requirements.txt includes geopandas, rasterio, rioxarray, pyarrow and planetary-computer, all of which have compiled or system-level pieces that pip resolves less predictably. The repository Dockerfile installs the package from conda-forge with mamba, which is the only install command the project shows:

RUN mamba install -n base -c conda-forge \
    geoai \
    overturemaps -y && \
    fix-permissions "${CONDA_DIR}"

The same Dockerfile sets three environment variables that matter if you run the package inside a container or behind Jupyter: PROJ_LIB=/opt/conda/share/proj, GDAL_DATA=/opt/conda/share/gdal and LOCALTILESERVER_CLIENT_PREFIX='proxy/{port}'. The last one is what lets the tile server work through Jupyter's proxy rather than on a bare port. For a Python session, the README's stated purpose is that you can perform tasks such as building footprint extraction, land cover classification and change detection with a few lines of code, and the package is imported under the name geoai. The README points to notebook examples and to a book at book.opengeoai.org for the actual workflows; it does not print a runnable snippet of its own. If you want the QGIS route instead, the README links a dedicated plugin page at opengeoai.org/qgis_plugin, and the plugin runs inside the QGIS desktop environment so you do not write Python at all.

Where the abstraction leaks

The dependency surface is the first real cost. requirements.txt pins torch>=2.10.0, transformers>=4.56.2, datasets>=4.8.4, tokenizers>=0.22.2 and leafmap>=0.63.1, on top of torchgeo, albumentations, opencv-python-headless and scikit-image. That is a large environment to keep coherent, and pyproject.toml requires Python 3.12 or newer, which rules out older interpreters outright. The project also splits optional functionality into extras: onnx, sr, rfdetr, terratorch, vllm, networks, agents, building, osd and extra. Anything in those extras is not present after a plain install, so a tutorial that imports an ONNX runtime path or a Terratorch model will fail until you install the matching extra. Second, the README documents no rollback behaviour, no dataset versioning and no way to pin a pretrained checkpoint to a specific revision, which matters if you need to reproduce a result months later. Third, the QGIS plugin and the Python API are separate surfaces with separate installation paths, and the README does not describe how model artifacts move between them. Finally, this is not a vector analysis toolkit. If your problem is network routing, topology cleaning or attribute joins, the geospatial libraries in requirements.txt will serve you better without the torch stack attached.

GeoAI against TorchGeo, on the same problem

The README names TorchGeo as a foundational library and describes the gap as high-level interfaces above that layer. The difference in approach is worth being concrete about. TorchGeo supplies datasets, samplers and transforms that understand geospatial metadata, and you write the training loop, the checkpointing and the inference wrapper yourself. geoai-py supplies the loop, the chip generation and the inference pipeline, and you accept its choices. That trade runs in both directions. With TorchGeo you can swap a sampler or a loss function without fighting an abstraction; with geoai-py you get building footprint extraction or land cover classification without writing the plumbing, and you inherit whatever the package decided about tiling, augmentation and device placement. The same reasoning applies to the other libraries the README lists. TerraTorch targets foundation-model fine-tuning with a configuration-driven approach, and SRAI focuses on spatial representation learning. None of them ship a QGIS plugin or a console entry point, which is the part of geoai-py that is genuinely distinct.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent: v0.41.2 on 2026-07-16, v0.42.0 on 2026-07-25 and v0.43.0 on 2026-09-03. That cadence is good for fixes and bad for stability, because a minor version bump can move a pinned dependency. pyproject.toml carries a bumpversion configuration that commits and tags on each release, and the version is declared in two places, the [project] table and [tool.bumpversion], so reading the installed version from package metadata is more reliable than reading the file. The licence is MIT, declared both in the LICENSE file and in the pyproject classifier, which permits commercial and closed-source use; the practical constraint is that the dependency tree is not uniformly permissive in the same way, and the extras pull in packages with their own terms. That is a question for your own review, not something the README answers. For upgrade cost, note the [tool.uv] constraint-dependencies block, which pins aiohttp>=3.13.4, requests>=2.33.0 and cryptography>=46.0.6 to resolve security advisories. If you manage the environment with something other than uv, those minimums are not enforced for you.

What the repository layout tells you that the README does not

The README is a feature tour. The file listing is closer to a roadmap. Alongside the geoai/ package there is agent-harness/, geoai-mcp-server/, qgis_plugin/, paper/, scripts/ and tests/, plus a zensical.toml documentation config and a pytest.ini. The presence of an MCP server and an agent harness, matched by the agents extra pulling in strands-agents with Ollama, Anthropic and OpenAI backends, says the project is betting on model-driven workflows rather than only on scripted ones. That is a meaningful direction, and it is also the least documented part of what is visible here. The CITATION.cff and the JOSS paper reference give the project an academic citation path, which matters if you need to justify the dependency in a grant or a methods section. The paper/ directory suggests the JOSS submission is maintained in-tree. None of this is a reason to adopt or avoid the package, but it does tell you where the maintainer's attention is going, and it is not the QGIS plugin.

Editorial conclusion

Adopt geoai-py if you want the training loop and the data plumbing in one place and you are willing to accept the dependency footprint; the README states the package requires Python 3.12 or newer, so check that against your existing environment before anything else. Skip it if you need a minimal install, if your work is vector-only, or if you already have a TorchGeo pipeline you are happy maintaining. Before committing, confirm that a conda-forge or PyPI install resolves on your platform, and read the requirements.txt pin on torch>=2.10.0 against whatever CUDA build your machine already has.

Frequently asked questions

Official sources

1. License: MIT
2. opengeos/geoai on GitHub
3. Project website
4. README
5. Releases