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, config_options=None, mask_and_scale=None, decode_times=None, decode_timedelta=None, use_cftime=None, concat_characters=None, decode_coords=None)

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 (dimensions not named keep a single chunk). Chunking is delegated to Dataset.chunk so chunked arrays are created by xarray's active chunk manager rather than by this backend (issue #31); dask is only required when chunks is not None.	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. Bands reporting differing nodata/scale/offset cannot be CF-decoded as one variable: values are returned raw with per-band metadata in band_nodata/band_scale_factor/band_add_offset coordinates and a warning is emitted (use band_as_dim=False to decode each band independently).	True
config_options	dict	GDAL configuration options, e.g. {"GDAL_HTTP_MAX_RETRY": "3", "GDAL_HTTP_RETRY_DELAY": "5"}. Applied thread-locally around the open and around every subsequent read, including per-thread reopens under dask (issue #34) and reads on distributed workers after unpickling, then unset again, so concurrent opens with different options do not interfere. Values are stringified. Not applied during engine auto-detection (guess_can_open).	None
mask_and_scale	bool	If True (default), apply CF mask/scale decoding: nodata becomes NaN and scale_factor/add_offset are applied, with the original values recorded in each variable's encoding. If False, return raw values with the CF attributes left in attrs.	None

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"],
)