pint-xarray

library0.6.1pypypi✓ verified 84d ago

pint-xarray provides an interface between Pint (physical units library) and xarray (labeled multi-dimensional arrays). It enables attaching units to `xarray.DataArray` and `xarray.Dataset` objects, performing unit-aware computations, and ensuring dimensional consistency, making scientific data processing more robust. It is currently at version 0.6.1 and sees active development with releases typically tied to feature additions and bug fixes.

data serialization

pip install pint-xarray

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PINT-XARRAY

pint-xarray

datapythonv0.6.1

Install

9.2s avg

Import

2505ms

Disk

184MB

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.5.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

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 2.582s · 181.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 9.2s · import 2.428s · 174MB

184MB installed

● package 184MB

Code

Verified usage

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

pint_xarray

✓ import pint_xarray

Importing `pint_xarray` is necessary to register the `.pint` accessor on xarray objects. It doesn't typically require direct symbol usage, just the import side-effect.

DataArray.pint

✓ da.pint.quantify(...)

✗ da.attrs['units'] = 'meter'

The preferred way to attach units since v0.5.0 is via the `.pint` accessor, not direct attribute manipulation.

Dataset.pint

✓ ds.pint.quantify(...)

✗ ds['var'].attrs['units'] = 'meter'

Units for Dataset variables should be managed via the `.pint` accessor for unit-awareness.

This quickstart demonstrates how to initialize `xarray.DataArray` and `xarray.Dataset` objects with physical units using the `.pint` accessor. It shows how to quantify variables and perform unit conversions, highlighting the core functionality of unit-aware data handling.

import xarray as xr import pint_xarray # noqa: F401 (registers accessor) import pint import numpy as np # Create a Pint UnitRegistry ureg = pint.UnitRegistry() # Create an xarray DataArray with units using the .pint accessor da = xr.DataArray( np.array([10.0, 20.0, 30.0]), coords={"x": [0, 1, 2]}, dims=("x",), ).pint.quantify(unit=ureg.meter) print("Original DataArray:") print(da) # Perform a unit-aware operation: convert units da_km = da.pint.to("kilometer") print("\nConverted to kilometers:") print(da_km) # Example with a Dataset and multiple variables ds = xr.Dataset( { "temperature": ("time", [25.0, 26.0]), "pressure": ("time", [1013.25, 1012.00]) }, coords={"time": [0, 1]} ).pint.quantify({"temperature": ureg.degC, "pressure": ureg.hPa}) print("\nOriginal Dataset variable 'temperature':") print(ds["temperature"]) # Convert a Dataset variable's units temp_kelvin = ds["temperature"].pint.to("kelvin") print("\nTemperature in Kelvin:") print(temp_kelvin)

Debug

Known issues

breakingStarting from version 0.5.0, `pint-xarray` changed its internal unit storage mechanism. Units are now stored as `pint.Quantity` objects within a custom `pint_units` backend, rather than as strings in `xarray.DataArray.attrs`. This enhances unit propagation and ensures better integration with Pint's features.

fix

Migrate code to use the `.pint.quantify()` method to explicitly attach units, and avoid direct manipulation of `attrs['units']` if unit-awareness is desired. Existing data saved before 0.5.0 might need re-quantifying upon loading.

affects: >=0.5.0

deprecatedThe `convert_units` function (e.g., `pint_xarray.convert_units(da, 'meter')`) has been removed in favor of the `.pint.to()` accessor method.

fix

Replace calls to `pint_xarray.convert_units(obj, unit)` with `obj.pint.to(unit)`.

affects: >=0.5.0

gotchaWhen performing operations with quantified xarray objects, Pint's strict unit checking will enforce dimensional consistency. Attempting operations on quantities with incompatible dimensions will raise a `DimensionalityError`.

fix

Always ensure units are dimensionally compatible before an operation. Use `da.pint.to(target_unit)` or `da.pint.to_base_units()` to explicitly convert units if needed.

affects: all

gotchaUsing `pint-xarray` for computations will ensure unit propagation for many operations, but it does not magically resolve all unit inconsistencies in every scenario. For example, some non-unit-aware xarray methods might still drop unit metadata if not handled correctly.

fix

Always verify the units after complex operations, especially when chaining multiple xarray methods. If units are unexpectedly dropped or behave strangely, consider applying `.pint.quantify()` or `.pint.dequantify()` at critical points, or using `.pint.to()` to harmonize units before operations.

affects: all

Errors

Common errors & fixes

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

The `pint_xarray` accessor was not registered with xarray. This happens if `import pint_xarray` is omitted or placed after the `xarray.DataArray` creation in certain environments.

fix

Add `import pint_xarray` at the beginning of your script or before you attempt to use the `.pint` accessor. The import statement itself registers the accessor.

pint.errors.DimensionalityError: Cannot convert from 'meter' to 'second'

You attempted an operation (e.g., addition, conversion) between two quantities that have fundamentally incompatible dimensions (e.g., length and time). Pint strictly enforces dimensional correctness.

fix

Review the units of the involved DataArrays or Quantities. Ensure they are dimensionally compatible before performing the operation. If a conversion is intended, ensure the target unit is dimensionally consistent (e.g., `da.pint.to('kilometer')` for a meter-quantified array).

Upgrade

Version history

0.6.1latest on PyPI · released Mar 23, 2026

Audit

Dependencies

xarrayrequiredCore dependency for labeled multi-dimensional arrays.

pintrequiredCore dependency for physical units management.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/xarray-contrib/pint-xarray ↗

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

docshttps://pint-xarray.readthedocs.io/en/stable ↗