xarray

library2026.7.0pypypi✓ verified 26d ago

Xarray (pronounced 'ex-array') is an open-source Python package that simplifies working with labelled multi-dimensional arrays and datasets. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, enabling a more intuitive and less error-prone experience for scientific computing and data analysis, particularly for earth sciences. As of February 2026, the current version is 2026.2.0. Xarray maintains a regular release cadence, with minor versions typically released monthly or bi-monthly.

data serialization http-networking

pip install xarray

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · XARRAY

xarray

datapythonv2026.7.0

Install

21.8s avg

Import

2348ms

Disk

487MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.6.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

1/2 runs

✓ 20.25s

py 3.11

1/2 runs

✓ 21.35s

py 3.12

1/2 runs

✓ 20.05s

py 3.13

1/2 runs

✓ 20.4s

py 3.9

1/2 runs

✓ 27.1s

487MB installed

● package 487MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DataArray

✓ import xarray as xr; da = xr.DataArray(...)

Dataset

✓ import xarray as xr; ds = xr.Dataset(...)

xray

✓ import xarray as xr

✗ import xray as xr

The library was renamed from 'xray' to 'xarray' in January 2016. The 'xray' module no longer exists.

This quickstart demonstrates the creation of a basic `DataArray` and a `Dataset`, including dimension names, coordinates, and attributes. It then shows how to perform a simple aggregation (mean) on a variable within the `Dataset` along a specified dimension.

import xarray as xr import numpy as np import pandas as pd # Create a DataArray data_array = xr.DataArray( np.random.rand(2, 3), coords={"x": [10, 20], "y": ["a", "b", "c"]}, dims=("x", "y"), name="random_data" ) # Create a Dataset with two DataArrays sharing coordinates temp = xr.DataArray( 25 + 10 * np.random.randn(2, 3, 4), coords={ "time": pd.to_datetime(["2026-01-01", "2026-01-02"]), "lat": [40, 50], "lon": [100, 110, 120, 130] }, dims=("time", "lat", "lon"), name="temperature", attrs={"units": "Celsius", "long_name": "Air Temperature"} ) precip = xr.DataArray( 5 * np.random.rand(2, 3, 4), coords=temp.coords, # Share coordinates from temp dims=temp.dims, name="precipitation", attrs={"units": "mm", "long_name": "Precipitation Rate"} ) dataset = xr.Dataset({"temp": temp, "precip": precip}) # Perform a simple operation (e.g., mean over 'time' dimension) mean_temp = dataset["temp"].mean(dim="time") print("DataArray:\n", data_array) print("\nDataset:\n", dataset) print("\nMean temperature over time:\n", mean_temp)

Debug

Known issues

breakingDefault attribute preservation behavior changed in `xarray` v2025.11.0. All operations now preserve attributes by default. Previously, attributes were dropped unless `keep_attrs=True` was explicitly set. Binary operations now combine attributes using `drop_conflicts` instead of keeping only the left operand's attributes.

fix

Review code that relies on attributes being dropped by default. If the old behavior is desired, explicitly set `keep_attrs=False` or manually manage attributes.

affects: >=2025.11.0

breakingDirect application of certain NumPy ufuncs to `xarray.DataArray` objects may now raise `NotImplementedError` due to the `__array_ufunc__` protocol. This affects ufuncs that previously implicitly converted `DataArray` to a NumPy array.

fix

Explicitly convert the `DataArray` to a NumPy array using `.values` before applying the NumPy ufunc (e.g., `np.add.reduce(da.values)`).

affects: >=0.10.2

breakingThe behavior of `Dataset.identical()`, `DataArray.identical()`, and `testing.assert_identical()` changed to include comparison of indexes. Two objects with identical data but different indexes will no longer be considered identical.

fix

If only data identity is required, compare the underlying data (`.values` or by casting to `pandas.DataFrame`). Adjust identity checks if index differences are now considered relevant.

affects: >=2026.2.0

gotchaA `ValueError` is raised when constructing an `xarray.DataArray` or `Dataset` if the size of a dimension in the input data does not match the length of its corresponding coordinate array.

fix

Ensure that the length of each coordinate provided for a dimension precisely matches the actual size of that dimension in the input data or dataset being constructed. For example, if data has shape `(3, 2)` for dimensions `('lat', 'lon')`, then `coords['lat']` must have length `3` and `coords['lon']` must have length `2`.

affects: >=0.1.0

breakingInstallation of 'netCDF4' (a common xarray backend) may fail in Alpine Linux environments due to missing HDF5 development headers. The build process for 'netCDF4' requires system-level HDF5 development libraries.

fix

To resolve this, install the HDF5 development package on your Alpine system (e.g., `apk add hdf5-dev`) before attempting to install 'netCDF4' or xarray with netCDF4 as a dependency.

affects: >=0.0.0

Errors

Common errors & fixes

ValueError: Cannot find the h5netcdf, netcdf4 or pydap backend. Please install one of them to use 'netcdf' engine.

The required backend library (e.g., `netcdf4`, `h5netcdf`, `zarr`) for reading or writing a specific file format is not installed in the Python environment.

fix

Install the appropriate backend library using `pip install netcdf4` (or `h5netcdf`, `zarr`, `cfgrib`, etc., as needed for your file type).

ValueError: encountered differing variable dimensions that cannot be reconciled

Attempting to merge or concatenate `xarray.Dataset` or `xarray.DataArray` objects that have conflicting dimensions for variables, or non-matching coordinates along a dimension when a strict compatibility check is used.

fix

Ensure dimensions and coordinates align appropriately, or use `xarray.concat()` with `coords='minimal'` or `compat='override'` if conflicts are expected, or explicitly select/rename variables/dimensions before merging.

KeyError: 'some_coordinate_or_variable_name'

An attempt was made to select or access a coordinate or variable using a name that does not exist in the `Dataset` or `DataArray`.

fix

Verify the exact name of the coordinate or variable using `ds.coords`, `ds.data_vars`, or `ds.dims` (for Dataset) or `da.coords` (for DataArray) and use the correct name in your selection.

TypeError: ufunc 'subtract' did not contain a loop with signature matching types

An arithmetic operation (like subtraction) was attempted between `xarray.DataArray` or `xarray.Dataset` objects (often backed by Dask arrays) that have incompatible data types, unaligned dimensions, or involve an operation not supported by the underlying ufunc for the given types.

fix

Ensure operands have compatible numeric data types using `.astype()`, explicitly align dimensions using `.align()`, or compute Dask arrays to concrete NumPy arrays using `.compute()` if the operation requires it.

Upgrade

Version history

2026.7.0latest on PyPI · released Jul 9, 2026

Audit

Dependencies

pythonrequiredCore requirement

numpyrequiredRequired for core array operations

pandasrequiredRequired for core data structures and compatibility

packagingrequiredRequired for dependency version management

daskoptionalOptional, for parallel and out-of-core computing

netCDF4optionalOptional, recommended for reading and writing NetCDF files

bottleneckoptionalOptional, for accelerating NaN-skipping and rolling window aggregations