Install & Compatibility
Where this runs
tested against v? · pip install
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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
open_dataset
✓ from cfgrib import open_dataset
✗ from cfgrib import open_dataset
open_file
✓ from cfgrib import open_file
Dataset
✓ from cfgrib import Dataset
Demonstrates how to open a GRIB file using `cfgrib` with `xarray`'s `open_dataset` function and inspect its contents. Requires a GRIB file to be present.
import cfgrib
import xarray as xr
import os
# --- IMPORTANT: Obtain a GRIB file for this example ---
# cfgrib requires a GRIB file to operate. For a runnable example:
# 1. Download a sample GRIB file, e.g., from:
# https://github.com/ecmwf/cfgrib/blob/main/tests/grib_files/era5-levels-members.grib
# 2. Save it as 'sample.grib2' in the same directory as this script,
# or specify its full path.
#
# Alternatively, if you have `earthkit-data` installed:
# import earthkit.data
# ds = xr.open_dataset(earthkit.data.res_source('t.grib'), engine='cfgrib')
grib_file_path = "sample.grib2"
if not os.path.exists(grib_file_path):
print(f"Warning: The GRIB file '{grib_file_path}' was not found.")
print("Please download a sample GRIB file and place it in the current directory or update the path.")
print("Skipping `open_dataset` call for this demonstration.")
else:
try:
# Open the GRIB file as an xarray Dataset
# The `engine='cfgrib'` is crucial for xarray.open_dataset to use cfgrib
ds = xr.open_dataset(grib_file_path, engine="cfgrib")
print("\nDataset loaded successfully:")
print(ds)
# Access a data variable, e.g., 't' for temperature
if 't' in ds:
print("\nTemperature data (first 5 values):")
print(ds['t'].isel(time=0, level=0).values.flatten()[:5])
else:
print("\nNo 't' variable found in the dataset. Available variables:", list(ds.data_vars))
except Exception as e:
print(f"An error occurred while opening the GRIB file: {e}")
Debug
Known issues
gotchaThe `cfgrib` library is a Python wrapper around the ECMWF `ecCodes` C library. `ecCodes` must be installed separately and accessible in your system's PATH (or LD_LIBRARY_PATH on Linux/macOS) for `cfgrib` to function. `pip install cfgrib` does NOT install `ecCodes` itself.fixFor the easiest and most reliable installation, use `conda install -c conda-forge cfgrib eccodes`. If using `pip`, ensure `ecCodes` is installed system-wide first (e.g., via `apt`, `brew`, or source build), then `pip install cfgrib`.
affects: all
gotchaGRIB files can contain large volumes of data. Loading an entire file into an `xarray.Dataset` can consume significant memory, potentially leading to `MemoryError` or slow performance. `cfgrib` typically loads data lazily, but computations or slicing can trigger full loading into memory.fixFor very large GRIB datasets, be mindful of operations that force data loading. Consider using `xarray.open_mfdataset` for multiple files to leverage Dask's lazy computation, or process data in chunks if possible. Use `ds.chunks` to inspect Dask array chunking.
affects: all
gotchaWhile `cfgrib` aims for CF-compliance, some GRIB files may have non-standard metadata or structures that lead to unexpected coordinate interpretations (e.g., missing time dimensions, non-standard vertical levels, or unexpected grouping of parameters). This can require manual `set_index` or other `xarray` operations.fixThoroughly inspect the loaded `xarray.Dataset` (its `coords`, `dims`, and `data_vars`). If needed, manually adjust coordinates or dimensions using `xarray`'s API (e.g., `ds.set_index()`, `ds.swap_dims()`). Utilize `cfgrib`'s `index_keys` or `read_coords` options in `open_dataset` to guide interpretation.
affects: all
breakingPrior to xarray v2022.09.0, `xarray.open_dataset` used `backend_kwargs` to pass arguments to the underlying engine (`cfgrib` in this case). This keyword argument was renamed to `engine_kwargs` in newer xarray versions.fixIf using an xarray version 2022.09.0 or newer, change `backend_kwargs` to `engine_kwargs` when calling `xr.open_dataset`. Example: `xr.open_dataset(..., engine='cfgrib', engine_kwargs={'index_keys': ['time']})`. affects: xarray < 2022.09.0 uses `backend_kwargs`, xarray >= 2022.09.0 uses `engine_kwargs`.
Upgrade
Version history
0.9.15.1latest on PyPI · released Sep 30, 2025
Audit
Dependencies
xarrayrequiredCore data structures for representing GRIB data as NetCDF Common Data Model.
eccodesrequiredThe underlying ECMWF C library providing core GRIB encoding/decoding functionality. Absolutely required for cfgrib to function.
numpyrequiredFundamental package for scientific computing with Python, essential for data arrays.
pandasrequiredUsed for time series functionality and indexing within xarray.