cf-xarray

library0.11.3pypypi✓ verified 89d ago

CF-Xarray is a lightweight Python library that extends Xarray objects with an accessor (`.cf`) to interpret and utilize Climate and Forecast (CF) metadata conventions. It simplifies data analysis workflows by allowing users to refer to geophysical quantities by their standard CF names (e.g., 'latitude' instead of 'lat'), making code more generic across diverse CF-compliant datasets. The library is actively maintained as part of the `xarray-contrib` organization, with frequent releases.

data

pip install cf-xarray

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CF-XARRAY

cf-xarray

datapythonv0.11.3

Install

8.8s avg

Import

1516ms

Disk

180MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.6 · 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

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.559s · 177.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 8.8s · import 1.474s · 171MB

180MB installed

● package 180MB

Code

Verified usage

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

cf_xarray

✓ import cf_xarray

Importing the top-level package registers the .cf accessor on xarray objects. No direct import of classes is usually needed for basic usage.

Demonstrates loading an xarray dataset, accessing CF-compliant coordinates and axes via the `.cf` accessor, and performing an operation (mean) using CF standard names. It also shows how to use `guess_coord_axis()` for datasets with incomplete metadata.

import xarray as xr import cf_xarray # This registers the .cf accessor # Load a sample dataset (e.g., from xarray's tutorial data) ds = xr.tutorial.load_dataset("air_temperature") # Access CF-compliant coordinates print("CF-identified coordinates:", ds.cf.coordinates) print("Latitude variable name:", ds.cf["latitude"]) # Perform a mean operation using CF standard names mean_temp = ds.air.cf.mean("latitude") print("Mean temperature along latitude:\n", mean_temp) # Add missing CF attributes (if necessary) ds_incomplete = ds.copy(deep=True) ds_incomplete.lat.attrs.pop('standard_name') ds_incomplete.cf.guess_coord_axis(verbose=True) print("Guessed coordinates for incomplete dataset:", ds_incomplete.cf.coordinates)

Debug

Known issues

breakingXarray's default attribute handling changed in versions >= 2025.11.0. Operations now preserve attributes by default and combine attributes from both operands using `drop_conflicts` in binary operations, instead of keeping only the left operand's attributes. This might affect workflows relying on previous attribute-dropping behavior.

fix

Review xarray's documentation for attribute handling. If explicit attribute dropping or custom merging is needed, use `keep_attrs=False` or implement custom logic.

affects: xarray >= 2025.11.0

gotchacf-xarray's utility is highly dependent on the presence and correctness of CF-compliant metadata (attributes) in your xarray objects. If metadata is incomplete or non-standard, `cf-xarray` might not identify variables as expected.

fix

Inspect recognized attributes using `ds.cf.coordinates` or `ds.cf.axes`. Use methods like `ds.cf.guess_coord_axis()` or `ds.cf.add_canonical_attributes()` to infer or add missing metadata. Custom criteria can also be provided for identification.

affects: All versions

gotchaThe `cf.add_bounds()` method estimates coordinate bounds using linear interpolation and extrapolation. While effective for rectilinear grids, this can be a coarse approximation for curvilinear or irregular grids, potentially leading to inaccuracies or unmatching corners in complex geometries.

fix

Be aware of the limitations for non-rectilinear grids. For critical applications, prefer datasets with pre-calculated, explicitly provided bounds or grid metrics from the data producer.

affects: All versions

deprecatedXarray, cf-xarray's core dependency, dropped support for Python 2.7 in `xarray` v0.12.0. cf-xarray itself requires Python >=3.11.

fix

Ensure your environment uses Python 3.11 or later and the latest compatible version of xarray.

affects: xarray < 0.12.0 (and Python < 3.11 for cf-xarray)

Errors

Common errors & fixes

AttributeError: 'DataArray' object has no attribute 'cf'

The `cf-xarray` accessor has not been registered with xarray. This typically happens if `import cf_xarray` is omitted or executed after the xarray object is created and accessed.

fix

Add `import cf_xarray` at the beginning of your script or before any `.cf` accessor calls.

KeyError: 'latitude' (or similar CF standard name) when using ds.cf['latitude']

The xarray Dataset or DataArray lacks the necessary CF-compliant attributes (e.g., 'standard_name', 'axis', 'units') for cf-xarray to identify a variable as 'latitude'.

fix

Inspect `ds.cf.coordinates` or `ds.cf.axes` to see which CF attributes are recognized. You might need to manually add appropriate attributes to your xarray object (e.g., `da.attrs['standard_name'] = 'latitude'`) or use `ds.cf.guess_coord_axis()` to infer them.

ModuleNotFoundError: No module named 'xarray'

xarray is a mandatory dependency for cf-xarray, and it is not installed in the current Python environment.

fix

Install xarray: `pip install xarray cf-xarray`.

Upgrade

Version history

0.11.3latest on PyPI · released Jun 12, 2026

Audit

Dependencies

xarrayrequiredcf-xarray is an accessor for xarray DataArray and Dataset objects, providing CF-compliant functionality.

numpyrequiredRequired by xarray, which is a core dependency of cf-xarray.

pandasrequiredRequired by xarray, which is a core dependency of cf-xarray.

packagingrequiredRequired by xarray, which is a core dependency of cf-xarray.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xarray-contrib/cf-xarray.git ↗

packagehttps://pypi.org/project/cf-xarray/ ↗

homepagehttps://cf-xarray.readthedocs.io ↗

docshttps://cf-xarray.readthedocs.io ↗

changeloghttps://cf-xarray.readthedocs.io/en/latest/whats-new.html ↗