xarray-spatial: raster analysis on labelled arrays, without GDAL

150 functions over the array you already have

Xarray-Spatial is a Python library for raster analysis built on xarray, described in the repository as a fast and accurate library for raster operations. The README positions it as general purpose spatial processing geared towards GIS professionals.

The functional range is broad. There are more than 150 functions across surface analysis, hydrology with D8, D-infinity and MFD, fire behaviour, flood modelling, multispectral indices, proximity, classification, pathfinding and interpolation. What ties them together is the data model rather than the subject matter. Every function takes and returns labelled arrays, so a terrain function and a classification function compose with the same xarray machinery.

The deployment story is the other half of the design. It is extensible with Numba, scalable with Dask, GPU-accelerated with CuPy and Numba CUDA, and free of GDAL and GEOS dependencies. The last point is the one that changes how you install and ship a pipeline, and it is not incidental: the library includes a built-in GeoTIFF and COG reader and writer for raster I/O, so reading and writing rasters does not pull in the geospatial C stack.

Who this is for is a Python team that already holds raster data in xarray DataArrays, perhaps from a climate or remote sensing pipeline, and wants analysis functions that respect the labels and compose with the rest of an xarray workflow. The documentation is hosted at xarray-spatial.readthedocs.io, and the README lists badges for PyPI and conda-forge, the CI workflows, the documentation status and code coverage.

The examples directory shows the intended use cases in executable form, with erosion_simulation.py, fire_propagation.py, flood_simulation.py, landslide_risk.py, animated_hillshade.py, contour_explorer.py, glcm_texture_explorer.py, watershed_explorer.py and cost_distance_sim.py, plus a GPU viewshed notebook, a pathfinding notebook on the Austin road network and a set of user guide notebooks.

Automatic dispatch across four backends

The mechanism that makes the library usable in more than one environment is automatic dispatch. Functions dispatch automatically across four backends: NumPy, Dask, CuPy and Dask with CuPy.

That is a concrete claim about data flow rather than a slogan. The same function call runs eagerly on a NumPy array, runs lazily and in parallel on a Dask array, and runs on the GPU through CuPy. For a flood or fire propagation simulation that touches the same raster many times, the difference between an eager in-memory loop and a Dask graph is the difference between a laptop and a cluster, and the difference between CuPy and NumPy is the difference between a CPU and a device.

The Numba dependency is what makes the numeric work fast in the first place. It is listed as the extension mechanism, and it is also what allows the CuPy path to exist through Numba CUDA. The README links both the Numba project and the Numba CUDA documentation as the GPU route.

The lazy behaviour deserves a note for Dask users, because it is the classic source of confusion. A Dask-backed function returns a lazy graph, so nothing computes until you ask for the values. A pipeline that computes intermediate results inside a loop will therefore behave very differently from the same code on a NumPy array. The repository keeps a benchmarks/ directory and a set of dask examples under examples/dask/, which is where to look for how the authors expect the two modes to be used.

One point the README does not make is which functions support which backend. A library that dispatches across four backends rarely covers every function on every backend, and the documentation is the place to check whether, say, a specific pathfinding or interpolation routine is available under Dask or on the GPU.

Installing with the plot and vector extras

Installation is pip or conda, and the extras are the part worth reading carefully because they map onto actual dependencies.

# via pip
pip install xarray-spatial

# with plotting helpers (matplotlib)
pip install xarray-spatial[plot]

# with vector rasterization (shapely): rasterize, polygonize
pip install xarray-spatial[vector]

# via conda
conda install -c conda-forge xarray-spatial

The plot extra pulls in matplotlib for the plotting helpers. The vector extra pulls in shapely and exists for two functions, rasterize and polygonize, which is a useful signal about the scope of the vector support. It is a bridge into the raster world, not a vector analysis library, and if your workflow is dominated by vector geometry this is the wrong dependency.

The package is on both PyPI and conda-forge, and the README shows badges for the latest version on each channel plus download counters. The conda-forge route is worth noting for GPU users, since a conda environment is usually the easier way to get a CuPy build that matches your CUDA version.

The packaging itself has an unusual wrinkle that shows up in setup.py. The build system in pyproject.toml requires build, param, pyct and setuptools 54.1.2 or newer, and setup.py imports pyct.build and calls pyct.build.examples on the examples directory before the setup call when the develop argument is absent, then removes that directory afterwards. Version numbers come from setuptools_scm, with use_scm_version writing to xrspatial/_version.py. In plain terms, the version is derived from the git tag rather than hardcoded, which is why the release tags and the PyPI versions move together.

The xrspatial CLI pulls down the notebooks and the sample data

The library ships a command line entry point for the example material, and it is the fastest way to get something running.

xrspatial examples
xrspatial copy-examples
xrspatial fetch-data

xrspatial examples downloads both the example notebooks and the data they use. xrspatial copy-examples downloads the notebooks but not the data, and the README warns that you will not be able to run many of the examples in that state. xrspatial fetch-data downloads only the data and not the notebooks.

In all three cases the files land in a folder named xrspatial-examples inside your current directory, so the command is safe to run from a scratch folder and the data does not land in your site-packages.

The data is the reason this CLI exists. A geospatial library whose examples depend on downloaded terrain and imagery is not much use until you have that imagery, and the fetch commands remove a manual download step that would otherwise dominate a first run. The examples/datasets.yml file in the repository is the manifest behind this, listing the datasets the examples need.

A caveat for a restricted environment: the download is a network operation against remote data, so on an air-gapped machine you need another route to the same files, whether that is a manual copy or a mirror. The README does not describe an offline installation path for the sample data.

A feature freeze before 1.0.0, and an AI-assisted contribution policy

Two notices at the top of the README shape how anyone should approach this project today.

The first is a feature freeze. The project is working toward its first major release, 1.0.0, and until that ships only bug fixes, test coverage, performance work and documentation pull requests will be considered. New feature proposals will be triaged but not implemented until after the release. For a user, that is mostly good news, because the API is not going to move under you. For a contributor, it means the work that gets merged is maintenance work.

The second notice is unusual enough to quote. The README states that xarray-spatial uses AI assistance more aggressively than other open source projects, and it asks that before opening a pull request you read the AI-Assisted Contribution Policy in AI_POLICY.md and run your changes through the project's approved AI review workflow, described as a command suite in the xarray-spatial-skills repository. It states that pull requests which ignore the workflow are likely to be rejected.

The repository layout backs that up. Alongside AI_POLICY.md there is a CLAUDE.md, a .claude/ directory, a .codex/ directory and a .kilo/ directory, which are the configuration directories for the different coding assistants the project supports. There are also two files named .efficiency-audit-baseline.json, one of them suffixed .prev, which suggests the project tracks an efficiency audit baseline across changes.

The project is also asking for help with the workflow itself, saying it is looking for contributors to run the pre-defined AI-assisted workflows as v1.0.0 approaches, and asking those people to open an issue and flag the maintainer.

Whether you like that or not, it is a governance choice rather than a technical one, and it is documented at the top of the README rather than buried in CONTRIBUTING.md.

The alternative is a GDAL and GEOS based raster stack

The realistic comparison is with the conventional geospatial Python stack, where raster I/O and vector operations come from GDAL and GEOS through rasterio, fiona, shapely and friends, and analysis functions are either written by hand or taken from libraries such as whitebox-tools or scipy.

The difference in approach is where the work happens. In a GDAL based stack, the file format handling is done by a compiled C library with its own dependency tree, and the analysis functions operate on arrays you load yourself. In Xarray-Spatial, the raster I/O is a built-in GeoTIFF and COG reader and writer, and the analysis functions are dispatched onto the array backend, so the same code path runs on NumPy, Dask or CuPy.

That has two practical consequences. First, on a machine where installing GDAL is the hard part, a library with no GDAL or GEOS dependency removes an entire class of installation problems. Second, on a cluster, Dask dispatch means the same function call scales without rewriting the algorithm, and on a GPU workstation, CuPy and Numba CUDA give you device execution for the kind of iterative numerical work that raster analysis is made of.

The cost of the choice is scope. This is a raster analysis library, and its vector support is the two functions, rasterize and polygonize, behind an optional shapely extra. If your workflow needs vector overlay, network analysis on arbitrary geometry, or topology editing, you still need the other stack. The GEOS and GDAL free claim is about what this library needs to do its own job, not about what your project needs overall.

There is also the managed alternative of commercial or hosted raster analytics services. The difference there is that the processing leaves your environment, which is the wrong trade for exploratory work on large arrays and the right trade when the deliverable is a processed tile rather than a library.

MIT licence, a 0.10.x line and a 1.0.0 that has not arrived

The licence is MIT, stated in the LICENSE.txt file at the repository root and in the README's licence panel. For a scientific and geospatial library that most teams will vendor into an internal pipeline or a commercial product, that is the least encumbered grant available, and it is the single most important adoption fact in the README.

The release line is at 0.10.x. The listed releases are v0.10.19 on 2026-10-07, v0.10.18 on 2026-08-27 and v0.10.17 on 2026-07-17. The repository is not archived and the last push was on 2026-10-12, so the tree is actively worked on.

Two version numbers in play. The 0.x version is the published package version, and the freeze notice points to 1.0.0 as the first major release, which is when the API contract becomes stable. Until then, patch level bumps in 0.10.x can still carry behavioural changes, so a production pipeline should pin an exact version rather than track the 0.10 series.

The packaging is worth knowing about if you build from source. The build backend requires build, param, pyct and setuptools, the version comes from setuptools_scm through a _version.py file written at build time, and the examples directory inside the package is built and then removed during packaging. That last step is why the CLI commands exist, since the packaged library does not ship the notebooks or the data.

The repository also carries the usual supporting files for a project of this size: a CHANGELOG.md, a RELEASE.md, a CONTRIBUTING.md, a CODE_OF_CONDUCT.md, a Citation-styles.md, a benchmarks/ directory, a codecov.yml, a .readthedocs.yml for the documentation build and a MANIFEST.in for the sdist contents. The citation styles file is a small signal that the project expects to be cited in research work, which is a reasonable expectation for a spatial analysis library.

Editorial conclusion

Xarray-Spatial fits geospatial Python teams already working with labelled xarray arrays who want terrain, hydrology, proximity, classification and pathfinding functions that keep working with Dask laziness and can move to GPU, and who want to avoid a GDAL and GEOS install. It does not fit vector-heavy work, since vector support is an optional extra limited to rasterize and polygonize, and it does not fit teams that need new algorithms now, because the feature freeze holds until 1.0.0 ships. Verify first which of your existing environment's extras you need, since plot and vector are separate installs, and read the AI-assisted contribution policy before you plan any pull request.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xarray-contrib/xarray-spatial on GitHub