Install & Compatibility
Where this runs
tested against v1.0.2 · 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
muslpy 3.10–3.980 runs
installs and imports cleanly · install 0.0s · import 0.000s · 234.1MB
glibcpy 3.10–3.980 runs
installs and imports cleanly · install 7.4s · import 0.000s · 225MB
235MB installed
● package 235MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Grid
✓ from gridData import Grid
✗ from griddataformats.grid import Grid
This quickstart demonstrates how to create a `Grid` object with a `Field` representing temperature data, save it to a NetCDF file, and then read it back. Note that using `NetCDFFile` requires the optional `netcdf4` dependency (install with `pip install griddataformats[netcdf]`).
import tempfile
import os
import numpy as np
from griddataformats.grid import Grid
from griddataformats.common import Dimension, Field, Unit, Origin, GridType
from griddataformats.file import NetCDFFile # Requires 'netcdf4' optional dependency
# Create a simple 2D grid with dummy data
latitude = np.linspace(40, 50, 10)
longitude = np.linspace(-100, -90, 15)
temperature_data = np.random.rand(len(latitude), len(longitude)) * 30 + 273.15 # Kelvin
lat_dim = Dimension("latitude", latitude.shape[0], Unit.degree_north, data=latitude)
lon_dim = Dimension("longitude", longitude.shape[0], Unit.degree_east, data=longitude)
temp_field = Field(
name="temperature",
dimensions=[lat_dim, lon_dim],
units=Unit.kelvin,
data=temperature_data,
description="Surface Temperature"
)
grid = Grid(fields=[temp_field], grid_type=GridType.regular_latitude_longitude)
# Save to a temporary NetCDF file
with tempfile.TemporaryDirectory() as tmpdir:
filepath = os.path.join(tmpdir, "my_grid.nc")
NetCDFFile.from_grid(grid, filepath)
print(f"Grid saved to {filepath}")
# Now read it back
read_grid = NetCDFFile(filepath).to_grid()
print(f"Read back grid with {len(read_grid.fields)} field(s).")
read_field = read_grid.fields[0]
print(f"Field name: {read_field.name}, Units: {read_field.units}")
print(f"Data shape: {read_field.data.shape}")
print(f"First data point: {read_field.data[0,0]:.2f} K")
Debug
Known issues
gotchaUsing `GRIB2File` or `NetCDFFile` requires additional optional dependencies (`eccodes` or `netcdf4` respectively). A `ModuleNotFoundError` will occur if these are not installed.fixInstall `griddataformats` with optional dependencies: `pip install griddataformats[grib2]` or `pip install griddataformats[netcdf]` (or both for full functionality).
affects: All versions >=1.0.0
gotchaThe `Grid` and `Field` objects expect `numpy.ndarray` for field data. Providing raw Python lists directly to `Field.data` might lead to unexpected behavior or require explicit conversion, impacting performance or causing errors in data manipulation.fixEnsure `Field.data` is a `numpy.ndarray`. Convert lists using `numpy.array(your_list)` before passing them to `Field`.
affects: All versions >=1.0.0
gotchaThe dimensions provided for a `Field` must exactly match the shape of the `data` array. A mismatch in `Dimension.size` attributes versus `data.shape` will raise a `ValueError`.fixCarefully align the `dimensions` list and their `size` attributes with the actual `data.shape` of the `numpy.ndarray` provided to `Field`.
affects: All versions >=1.0.0
Upgrade
Version history
1.2.0latest on PyPI · released May 23, 2026
Audit
Dependencies
numpyrequiredCore dependency for array manipulation and data storage within Grid objects.
netcdf4optionalRequired for reading and writing NetCDF files using NetCDFFile.
eccodesoptionalRequired for reading and writing GRIB2 files using GRIB2File.