xarray-spatial

0.9.7 verified Mon Apr 27 auth: no python

xarray-based spatial analysis tools built on top of xarray, dask, and numba. Current version 0.9.7, released frequently (several minor versions per year).

pip install xarray-spatial

Common errors

error ModuleNotFoundError: No module named 'xarray_spatial' ↓

cause Trying to import the wrong name. The correct top-level import is 'xrspatial'.

fix

Use 'import xrspatial' or 'from xrspatial import hillshade'.

error ImportError: cannot import name 'hillshade' from 'xrspatial' ↓

cause The function may have been moved or renamed. Check the version documentation.

fix

Ensure you have the correct version: 'pip install xarray-spatial[complete]' and import the correct module (e.g., 'from xrspatial import hillshade').

error TypeError: 'DataArray' object is not callable ↓

cause Trying to use a DataArray as a function. Common when mixing up xarray and numpy patterns.

fix

Ensure you call the function from xrspatial (e.g., 'hillshade(elevation)') not on the DataArray itself.

Warnings

gotcha The top-level import is 'xrspatial', not 'xarray_spatial'. Many users mistakenly try 'import xarray_spatial as xrs' which fails. ↓

fix Use 'import xrspatial' and functions like 'from xrspatial import focal'.

deprecated As of v0.9.0, many modules (e.g., zonal) now accept xarray DataArrays directly instead of requiring conversion to a specific format. Older code may break if not updated. ↓

fix Pass DataArray objects directly; avoid manual conversion to numpy arrays.

gotcha If you install without the 'complete' extra, some features like GeoTIFF I/O (via rioxarray) or GPU acceleration (via cupy) will not be available. Missing dependencies raise ImportError at runtime. ↓

fix Install with 'pip install xarray-spatial[complete]' or install missing extras individually.

gotcha Dask arrays can cause memory issues if not handled properly. Some functions (e.g., visibility) may silently convert dask arrays to numpy, leading to large memory usage. ↓

fix Use .compute() explicitly only when needed; for newer versions, use dask-backed operations.

breaking In v0.9.0, the 'rasterize' function signature changed: the 'like' parameter now expects a DataArray with the same spatial reference. Old code using 'like' with a rasterio dataset may break. ↓

fix Pass an xarray DataArray with a crs attribute as the 'like' parameter.

Install

pip install xarray-spatial[complete]

Imports

xrspatial
wrong
```
from xarray_spatial import xrspatial
```
correct
```
import xrspatial
```
The library is imported as 'xrspatial', not as a submodule of xarray_spatial.
focal
```
from xrspatial import focal
```
hillshade
```
from xrspatial import hillshade
```

Quickstart

Import the library and compute a hillshade from an xarray DataArray.


import xarray as xr
import xrspatial
from xrspatial import hillshade

# Create a sample elevation raster
ds = xr.tutorial.load_dataset('air_temperature').isel(time=0)
elevation = ds['air']

# Compute hillshade
hs = hillshade(elevation)
print(hs)