Install & Compatibility
Where this runs
tested against v2.47.1.20 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.6s · import 0.000s · 91MB
130MB installed
● package 130MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
findlibs_dependencies
✓ from eccodeslib import findlibs_dependencies
✗ import eccodes
This quickstart demonstrates how to open a GRIB file, iterate through its messages, extract common metadata keys like 'shortName' and 'paramId', and properly release resources. It highlights the importance of having a sample GRIB file and handles potential `FileNotFoundError` or `CodesInternalError` if the C library is not correctly set up.
import eccodes as ec
import os
# --- This quickstart requires a sample GRIB file. ---
# You can download sample GRIB files from ECMWF's website or find them in
# ecCodes/eccodes-python test directories, e.g., 'tests/data/regular_latlon_surface.grib2'.
# Replace 'path/to/sample.grib' with the actual path to your GRIB file.
# For example, a small GRIB file could be 'https://github.com/ecmwf/eccodes/blob/develop/tests/data/sample.grib2'.
GRIB_FILE_PATH = os.environ.get('ECCODES_SAMPLE_GRIB_PATH', 'path/to/sample.grib')
try:
print(f"Attempting to read GRIB file: {GRIB_FILE_PATH}")
message_count = 0
with open(GRIB_FILE_PATH, 'rb') as f:
while True:
# Get a new GRIB message handle from the file
handle = ec.codes_handle_new_from_file(f, ec.CODES_PRODUCT_GRIB)
if handle is None:
break # End of file
message_count += 1
# Access common keys
short_name = ec.codes_get(handle, 'shortName')
param_id = ec.codes_get_long(handle, 'paramId')
date = ec.codes_get_long(handle, 'dataDate')
time = ec.codes_get_long(handle, 'dataTime')
print(f" Message {message_count}: shortName={short_name}, paramId={param_id}, Date={date}, Time={time}")
# Release the handle to free memory
ec.codes_release(handle)
if message_count == 0:
print("No GRIB messages found in the file.")
else:
print(f"Successfully processed {message_count} GRIB messages.")
except FileNotFoundError:
print(f"Error: GRIB file not found at '{GRIB_FILE_PATH}'. Please ensure the file exists or set ECCODES_SAMPLE_GRIB_PATH.")
except ec.CodesInternalError as e:
print(f"Error processing GRIB file: {e}. Ensure ecCodes C library is installed and the GRIB file is valid.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `eccodeslib` Python package is a wrapper around the `ecCodes` C library. It requires the C library to be installed and accessible on your system. While pip wheels for Windows and macOS often bundle it, Linux users (and those installing from source) must install `ecCodes` separately (e.g., via `apt install libeccodes-dev` or `conda install -c conda-forge eccodes`). Installation or runtime will fail if the C library is not found.fixBefore `pip install eccodeslib`, ensure the `ecCodes` C library is installed using your system's package manager or via a method like `conda install -c conda-forge eccodes`.
affects: All versions of eccodeslib.
gotchaFailing to explicitly release `codes_handle` objects will lead to memory leaks and potential application crashes, especially when processing many GRIB/BUFR messages. `ec.codes_handle_new_from_file` creates a handle that must be manually freed.fixAlways call `eccodes.codes_release(handle)` after you are finished with a message handle. For file operations, ensure `with open(...)` is used, but this only closes the file, not the individual message handles.
affects: All versions.
gotchaecCodes keys have specific data types (e.g., `long`, `double`, `string`, `bytes`, `array`). Using the wrong getter/setter function (e.g., `ec.codes_get_long` for a string key) will result in `CodesInternalError` or incorrect data interpretation.fixConsult the ecCodes documentation (or use `codes_info -t` with the C library) to determine the correct type for each key. Use the appropriate `ec.codes_get_*` or `ec.codes_set_*` function, such as `ec.codes_get_string`, `ec.codes_get_long`, `ec.codes_get_double`, or `ec.codes_get_array`.
affects: All versions.
Upgrade
Version history
2.47.1.20latest on PyPI · released May 27, 2026
Audit
Dependencies
ecCodes C libraryrequiredeccodeslib is a Python binding for the ecCodes C library and requires it to be installed on the system. While pre-compiled wheels for Windows and macOS often bundle the C library, Linux users typically need to install ecCodes via their system's package manager (e.g., `apt install libeccodes0`, `yum install eccodes`) or from source before installing eccodeslib.