Installation#

Requirements#

xarray-spatial requires Python 3.12 or newer and runs on Linux, macOS, and Windows. The required core is small: numpy, numba, scipy, xarray, urllib3, and zstandard. There is no GDAL or GEOS anywhere in the stack, so nothing needs to be compiled and there are no system libraries to hunt down.

Setting up an environment#

Install into a fresh environment rather than your system Python. Any of the following works.

With venv (standard library):

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install xarray-spatial

With conda or mamba:

conda create -n xrspatial python=3.12
conda activate xrspatial
conda install -c conda-forge xarray-spatial

With uv:

uv venv
source .venv/bin/activate
uv pip install xarray-spatial

Optional dependencies#

The base install covers the raster compute functions plus GeoTIFF / COG read and write. The extras below add features on top. Combine them as needed:

pip install 'xarray-spatial[plot,vector,geotiff,reproject,dask]'

Extra	Installs	Enables
`plot`	matplotlib	The `.xrs.plot` accessor helpers.
`vector`	shapely	The vector-to-raster paths, `rasterize` and `polygonize`.
`geotiff`	deflate, pyproj	Faster DEFLATE compression (libdeflate) and full CRS support in the GeoTIFF writer. Without pyproj the writer only recognizes a small allowlist of EPSG codes.
`reproject`	pyproj	WKT / PROJ CRS resolution for reprojection.
`dask`	dask[array], dask-geopandas	Chunked, lazy, out-of-core processing on a single machine or a cluster. See Dask backend behavior.
`gpu`	cupy, cuspatial	The CuPy GPU backend. Needs an NVIDIA GPU and a CUDA toolkit matching your cupy build.
`optional`	awkward, geopandas, spatialpandas, rtxpy	Additional `polygonize` return types and the ray-traced `gpu_rtx` functions (rtxpy also needs cupy).
`examples`	datashader	Used by some of the example notebooks.
`doc`, `tests`	sphinx, pytest, …	Building this documentation and running the test suite.

GPU notes#

pip install 'xarray-spatial[gpu]' pulls in cupy and cuspatial. You also need an NVIDIA driver and a CUDA toolkit compatible with your cupy build; see the CuPy install guide if you are unsure which cupy package to pick.

Two GPU features have runtime dependencies that are not part of the gpu extra because they ship as system libraries:

libnvcomp – GPU batch decompression (DEFLATE, ZSTD) for the GeoTIFF GPU read path
kvikio – GPUDirect Storage, reading straight from SSD into GPU memory

Install both via conda from the rapidsai / nvidia channels. The rest of the GPU path works without them.

Cloud storage#

open_geotiff reads s3://, gs://, and az:// URLs through fsspec. Install fsspec plus the filesystem package you need: s3fs for S3, gcsfs for Google Cloud Storage, or adlfs for Azure. Plain http(s):// URLs work with no extra packages. Remote reads are an advanced-tier feature (see the feature matrix in the README and Stability policy and LTS commitment); GeoTIFF / COG has the details.

Verifying the install#

python -c "import xrspatial; print(xrspatial.__version__)"

A quick functional check that exercises the compute path, with no data download:

import numpy as np
import xarray as xr
from xrspatial import generate_terrain, hillshade

terrain = generate_terrain(xr.DataArray(np.zeros((300, 400)), dims=['y', 'x']))
print(hillshade(terrain).shape)