Written and maintained by CASRAI Editorial Board
Last updated
Xarray is a Python library for working with labeled, N-dimensional arrays and datasets, such as gridded climate, weather and ocean data. This guide is for researchers who have a netCDF, GRIB or Zarr file and need to open it, select a region or time range by name, and write the result back out. Details were checked against the official xarray documentation on 2026-11-07.
What is xarray?
Xarray adds labels to array data: “Xarray introduces labels in the form of dimensions, coordinates and attributes” on top of raw array values. Its two core objects are the DataArray, a labeled N-dimensional array and an N-D generalization of a pandas Series, and the Dataset, a dict-like container of DataArrays that share dimensions (comparable to a pandas DataFrame, though the arrays may differ in dtype and dimensions). Because the labels travel with the numbers, the dimension names, coordinate values and attributes in a file become part of how you work with it. This is the same idea as technical metadata kept next to the data it describes.
What it is used for in research
Typical inputs are multi-dimensional gridded files: variables indexed by time, latitude, longitude and level. Xarray reads netCDF, GRIB and Zarr stores and can combine many files into one dataset. Sources of such data on this site include ECMWF weather datasets and ESGF and CMIP climate model data.
Pangeo
Pangeo is not a separate piece of software. Its own site describes it as “first and foremost a community promoting open, reproducible, and scalable science”, and lists xarray (“N-D labeled arrays and datasets in Python”), Dask (“Distributed arrays and advanced parallelism for analytics”) and Jupyter among the cross-domain libraries it helps develop (pangeo.io, read 2026-11-07).
Install or access (official source only)
Per the official installation page (read 2026-11-07), xarray requires Python 3.11 or later, with numpy 1.26 or later, packaging 24.1 or later and pandas 2.2 or later. The documented install commands are:
conda install -c conda-forge xarray dask netCDF4 bottleneck
python -m pip install xarrayOptional dependency groups are installed with pip extras: xarray[io], xarray[accel], xarray[parallel], xarray[viz] and xarray[complete]. For file reading, the documentation lists netCDF4 (recommended), scipy (netCDF3 fallback), h5netcdf, zarr, and cftime (for non-standard calendars and dates outside roughly 1678 to 2262).
Step-by-step task: open, select, and write a gridded file
- Open a netCDF file.
import xarray as xr, thends = xr.open_dataset("example.nc", engine="netcdf4"). - Or open many files as one dataset.
ds = xr.open_mfdataset("my/files/*.nc", parallel=True)concatenates and merges multiple files. - Select by label. Name the dimension and give the label:
da.sel(time=slice("2000-01-01", "2000-01-02")). Slices used with.selinclude both endpoints. - Or select by integer position.
da.isel(space=0, time=slice(None, 2))ignores the labels and counts positions along each named dimension. - Match the nearest label when values are not exact.
da.sel(x=[1.1, 1.9], method="nearest"). The documentation notes thatmethodis not supported when any argument to.sel()is a slice. - Write to netCDF.
ds.to_netcdf(path). By default the file is saved as netCDF4, assuming netCDF4-Python is installed;unlimited_dims=["y"]marks a dimension as unlimited. - Or write to Zarr.
ds.to_zarr(path), and read it back withxr.open_zarr(path).
Can xarray open GRIB files?
Yes, through the cfgrib engine: xr.open_dataset("example.grib", engine="cfgrib"). The I/O documentation gives conda install -c conda-forge cfgrib as the install route. GRIB is the format used by many numerical weather prediction products; see the ECMWF guide for where such files come from.
Xarray to netCDF
The steps above (to_netcdf) are the documented route. The installation page lists scipy as the netCDF3 fallback, and netCDF4 as the recommended library for netCDF files.
Output and how to read it
Dimension names are the strings you pass as keywords (time=, space=, x=); they come from the dims argument or the first element of each (name, labels) pair when an array is built. For example, the documentation builds a 4 by 3 array with a time dimension (daily dates from 2000-01-01) and a space dimension (state codes IA, IL, IN).
Xarray vs pandas and NumPy: when to use xarray
Use xarray when your data has more than two named dimensions and you want to refer to them by name and select by label. The comparison below is drawn from the official “Why xarray?” page (read 2026-11-07).
| Library | What the documentation says |
|---|---|
| NumPy | Refers to dimensions by position; xarray lets you refer to dimensions by name and select by label rather than position. |
| pandas | Centers on the 1-D Series and 2-D DataFrame; xarray extends labels to N dimensions. |
| xarray | Labeled N-dimensional DataArray, and Dataset as a dict-like container of DataArrays sharing dimensions. |
For running the same analysis over many independent files, see also embarrassingly parallel jobs.
Troubleshooting
- Zarr store will not open. The documentation states “Xarray can’t open just any zarr dataset, because xarray requires special metadata”.
- GRIB or netCDF engine missing. The engine named in
engine=(cfgrib, netcdf4) is a separate package listed in the installation and I/O documentation. - Date problems. Non-standard calendars and dates outside about 1678 to 2262 require cftime.
- Nearest-label selection with a slice fails.
methodcannot be combined with slices in.sel().
Free alternatives
For work that does not need N labeled dimensions, the two libraries xarray is compared with are the alternatives:
| Alternative | Matched to (per Why xarray?) |
|---|---|
| pandas | 1-D and 2-D labeled data (Series, DataFrame) |
| NumPy | Plain N-dimensional arrays addressed by position |
FAQ
What is an xarray?
A Python library, and also the name of its labeled N-dimensional array object (DataArray), for scientific data with named dimensions, coordinates and attributes.
What is the main difference between pandas and xarray?
pandas centers on 1-D Series and 2-D DataFrames; xarray extends labels to N dimensions.
Can xarray open GRIB files?
Yes, with engine="cfgrib" once cfgrib is installed.
When to use xarray?
When your data has several named dimensions, such as time, latitude and longitude, and you want to select by label and read or write netCDF or Zarr.
Sources (official docs)
- Xarray: Installation (read 2026-11-07)
- Xarray: Why xarray? (read 2026-11-07)
- Xarray: Reading and writing files (read 2026-11-07)
- Xarray: Indexing and selecting data (read 2026-11-07)
- Pangeo (read 2026-11-07)
