---
id: xarray-dataclass
version: "3.0.0"
license: MIT License Copyright (c) 2020-2024 Akio Taniguchi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# xarray-dataclass — xarray data creation by data classes

License: permissive · Maintenance: active · Downloads: 78.2K/mo

## What it is and what it does

xarray-dataclass wraps xarray's DataArray and Dataset objects in a dataclass-based interface, letting you declare typed multidimensional data structures with fixed dimensions, coordinates, and attributes at definition time. Instead of building xarray objects imperatively with method calls, you define a dataclass using special type hints (Data, Coord, Attr, Name) that encode the structure, then instantiate it with `.new()` or NumPy-like factory methods (`.zeros()`, `.ones()`). The package validates that your data matches the declared schema and provides static type checking support through Pyright.

It is primarily useful for scientific and data-analysis workflows where you want to enforce a consistent structure across xarray objects—for example, ensuring all images in a batch have the same dimensions and dtype, or defining reusable templates for multidimensional datasets. The package depends on numpy, xarray, and typing-extensions; it is actively maintained and supports Python 3.9 through 3.13.

Use it for:

- Define reusable typed templates for multidimensional scientific data (e.g., images, time series, gridded fields) with fixed dimensions and dtypes.
- Create xarray DataArrays or Datasets with static type checking to catch dimension/dtype mismatches at development time.
- Build batch processing pipelines where all inputs must conform to a declared schema (e.g., all images must be 2D float arrays with x and y coordinates).
- Attach metadata (attributes, coordinate names) to xarray objects declaratively rather than imperatively after creation.
- Generate xarray objects with NumPy-like constructors (zeros, ones) while enforcing the declared structure.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Defines typed xarray DataArray and Dataset objects using Python dataclasses, with fixed dimensions, data types, coordinates, and attributes enforced at the class level.

Yes. The package is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for teams working with xarray who want type safety and schema enforcement. It is well-suited for scientific computing and data-analysis workflows where consistency and static checking add value. No known vulnerabilities.

## Install

pip install xarray-dataclass
uv add xarray-dataclass
poetry add xarray-dataclass

## Installing xarray-dataclass

Before you install: Low friction install with only three runtime dependencies (numpy, typing-extensions, xarray). Active maintenance as of August 2026 with recent commits.

License in practice: MIT License permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the original copyright notice.

Quickstart:

pip install xarray-dataclass

from dataclasses import dataclass
from typing import Literal
from xarray_dataclass import AsDataArray, Data, Coord

X, Y = Literal["x"], Literal["y"]

@dataclass
class Image(AsDataArray):
    data: Data[tuple[X, Y], float]
    x: Coord[X, int] = 0
    y: Coord[Y, int] = 0

image = Image.new([[0, 1], [2, 3]], x=[0, 1], y=[0, 1])

Requires Python 3.9 or later; xarray and numpy must be installed.

Verify before relying:

- Whether static type checking with Pyright works as advertised for all dimension and dtype combinations.
- Performance characteristics when working with large multidimensional arrays compared to raw xarray.
- Compatibility with xarray's latest versions beyond what the dependency specification guarantees.

## Package facts

- License: MIT License Copyright (c) 2020-2024 Akio Taniguchi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 78.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

typed xarray dataarray, dataclass xarray integration, xarray dataset with types, numpy array with type hints, structured xarray creation, type-safety, scientific-computing, data-structures

[View on SkillFed](https://skillfed.io/packages/xarray-dataclass) · [View on PyPI](https://pypi.org/project/xarray-dataclass/)