API Reference

Engine entrypoint

The xarray engine itself. Most users invoke it via xr.open_dataset(path, engine="gdalxarray", ...) rather than directly.

Bases: BackendEntrypoint

xarray backend for reading geospatial files via GDAL.

guess_can_open(filename_or_obj)

Conservative heuristic for xarray's engine auto-discovery.

open_dataset(filename_or_obj, *, drop_variables=None, chunks=None, multidim=True, group=None, band_as_dim=True)

Open a dataset using GDAL.

Parameters:

Name	Type	Description	Default
filename_or_obj	str	Path or GDAL-recognised URI (/vsicurl/, /vsis3/, vrt://, ZARR:, NETCDF:, /vsiicechunk/...).	required
drop_variables	iterable of hashable	Variables to omit from the returned Dataset.	None
chunks	dict	Chunk sizes for Dask arrays. None (default) returns a lazy non-Dask Dataset; {} uses GDAL's native block sizes; an explicit mapping like {"y": 256, "x": 256} is honoured.	None
multidim	bool	If True, use GDAL's multidimensional API (OpenEx + OF_MULTIDIM_RASTER). If False, use the classic raster API.	True
group	str	Group path for multidim datasets (e.g. "/group/subgroup"). Leading/trailing slashes are tolerated.	None
band_as_dim	bool	Classic-raster only. If True, bands become an xarray band dimension on a single band_data DataArray (the rioxarray- compatible idiom). If False, each band becomes a separate data variable named after its description (or band_N). The True default suits multispectral imagery; False is preferable when bands carry semantically distinct quantities.	True

Recipe builders

Helper functions that build GDAL configuration recipes - VRT strings, typically - for downstream consumption by the engine.

Lazy warp-VRT recipe construction.

The :func:warp function builds a description of a warp operation — target CRS, resolution, bounds, GCP/RPC/geoloc transformer, cutline, etc. — and returns it as VRT XML text. The result composes with :class:GDALBackendEntrypoint::

>>> import gdalxarray
>>> import xarray as xr
>>> vrt = gdalxarray.warp(source, crs="+proj=laea")
>>> ds = xr.open_dataset(vrt, engine="gdalxarray", multidim=False)

No pixels are read or written by warp() — the VRT is a recipe. Bytes flow only when the consumer (xarray, gdalwarp, gdal_translate) asks for a window.

warp(source, *, crs=None, bbox=None, shape=None, resolution=None, resampling='near', nodata=None, src_nodata=None, bands=None, **warp_options)

Build a warped-VRT recipe string.

Wraps :func:gdal.Warp with format="VRT" to produce a textual description of a reprojection / regrid / warp. The result is a self-contained VRT XML string that downstream tools can read lazily.

The named keyword arguments cover the common cases. Any further :func:gdal.WarpOptions keyword can be passed as an additional keyword argument and is forwarded verbatim — see GDAL's gdal.WarpOptions documentation for the full list (transformer options for RPC/GCPs/geolocation arrays, cutlines, alpha-band handling, working type, etc.).

Parameters:

Name	Type	Description	Default
source	str	GDAL-recognised source path or URI. Anything gdal.Open can handle: local file, /vsicurl/, /vsis3/, vrt://, ZARR:"...", NETCDF:...:var, etc.	required
crs	str or int	Target CRS as PROJ string, WKT, or EPSG code. Maps to GDAL's dstSRS.	None
bbox	sequence of 4 floats	Output bounding box (xmin, ymin, xmax, ymax) in target CRS units. Maps to GDAL's outputBounds.	None
shape	tuple of 2 ints	Output (width, height) in pixels. Maps to GDAL's width and height.	None
resolution	float or tuple of 2 floats	Output resolution. A scalar means isotropic (res, res). A tuple is (xres, yres). Maps to GDAL's xRes / yRes.	None
resampling	str	Resampling algorithm: "near", "bilinear", "cubic", "cubicspline", "lanczos", "average", "mode", "min", "max", "med", "q1", "q3", "sum", "rms". Maps to GDAL's resampleAlg.	``"near"``
nodata	float	Output nodata value. Maps to GDAL's dstNodata.	None
src_nodata	float	Override the source nodata value. Maps to GDAL's srcNodata.	None
bands	list of int	Subset of source bands to warp (1-based). Maps to GDAL's srcBands.	None
**warp_options		Any other keyword argument is forwarded to :func:gdal.WarpOptions verbatim. Common power-user options: rpc=True, tps=True, geoloc=True, transformerOptions=[...], cutlineWKT="POLYGON(...)", cropToCutline=True, coordinateOperation="+proj=...".	{}

Returns:

Type	Description
str	VRT XML describing the warped output. Suitable for xr.open_dataset(..., engine="gdalxarray"), for any GDAL tool that accepts a path, or for writing to a .vrt file as a portable, durable warp recipe.

Notes

Runtime-only options (multithread, warpMemoryLimit, creationOptions, callback, callback_data) are not serialised into the VRT description — they affect how a warp is executed, not what the warp produces. Passing them to warp() emits a :class:UserWarning and they are dropped. To control runtime behaviour for the eventual read, set GDAL config options on the consumer side, e.g.::

gdal.SetConfigOption("GDAL_NUM_THREADS", "4")
ds = xr.open_dataset(vrt, engine="gdalxarray")

Examples:

Reproject anything to Lambert Azimuthal Equal Area, lazily::

vrt = warp(src, crs="+proj=laea")
ds = xr.open_dataset(vrt, engine="gdalxarray", multidim=False)

Specific target grid::

vrt = warp(
    src,
    crs="EPSG:3577",
    bbox=(-2000000, -5000000, 2000000, -1000000),
    resolution=1000,
    resampling="bilinear",
)

Drone imagery with GCPs, warped via thin-plate splines::

vrt = warp(src, crs="EPSG:32755", tps=True)

Satellite Level-1B product with RPCs and a DEM::

vrt = warp(
    src,
    crs="EPSG:4326",
    rpc=True,
    transformerOptions=["RPC_DEM=/path/to/dem.tif"],
)