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-cuda12x	The CuPy GPU backend on CUDA 12. Needs an NVIDIA GPU and a matching driver.
`gpu-cuda13`	cupy-cuda13x	The same backend built against CUDA 13.
`optional`	awkward, geopandas, spatialpandas, rtxpy	Additional `polygonize` return types and the ray-traced `gpu_rtx` functions (rtxpy also needs cupy).
`examples`	matplotlib, geopandas, shapely	Used by the example notebooks for rendering and vector rasterization. datashader is no longer required.
`doc`, `tests`	sphinx, pytest, …	Building this documentation and running the test suite.

GPU notes#

CuPy publishes a separate wheel per CUDA major version, so the extra has to name one. Pick the one that matches your driver:

pip install 'xarray-spatial[gpu]'         # CUDA 12
pip install 'xarray-spatial[gpu-cuda13]'  # CUDA 13

Both pull the prebuilt wheel, so no local CUDA toolkit is needed – only an NVIDIA GPU and a driver new enough for that CUDA major. The CuPy install guide has the driver requirements.

Do not install the plain cupy package from PyPI. It is a source distribution that compiles CuPy from scratch and needs a full nvcc toolchain. If you manage your environment with conda, install cupy from conda-forge and skip both extras.

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)