Registry / data / eccodes

eccodes

JSON →
library2.48.0pypypi✓ verified 27d ago

The eccodes library provides a Python interface to the ECMWF ecCodes GRIB and BUFR decoder/encoder. It allows users to read, write, and manipulate GRIB and BUFR meteorological data files, providing both a low-level API mapping directly to the C library and a higher-level object-oriented interface. It is actively maintained by ECMWF with frequent releases, typically every 1-2 months, mirroring the underlying ecCodes C library.

pip install eccodes
INSTALL
IMPORT
SIG · ECCODES
E
eccodes
datapythonv2.48.0
Install
5.6s avg
Import
638ms
Disk
149MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.42.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 91.8MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 0.638s · 160MB
149MB installed
● package 149MB
Code
Verified usage

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

eccodes
✓ import eccodes
General import for accessing all eccodes functionalities.
codes
✓ from eccodes import codes
Import for low-level C API functions, e.g., codes.codes_open_file, codes.codes_get.
GribFile
✓ from eccodes import GribFile
High-level context manager for reading GRIB files, providing an iterator over GribMessage objects.
GribMessage
✓ from eccodes import GribMessage
High-level object representing a single GRIB message, allowing dictionary-like access to keys.
BufrFile
✓ from eccodes import BufrFile
High-level context manager for reading BUFR files, similar to GribFile.
BufrMessage
✓ from eccodes import BufrMessage
High-level object representing a single BUFR message, allowing dictionary-like access to keys.

This quickstart demonstrates how to open a GRIB file, iterate through its messages using the high-level `GribFile` context manager, and access common keys from individual `GribMessage` objects. It includes robust error handling and setup to create a dummy GRIB file if a real one isn't provided, ensuring the example is runnable out-of-the-box.

import eccodes import os # --- Quickstart setup: Ensure a GRIB file exists for demonstration --- # In a real scenario, you would point to your actual GRIB file. grib_filepath = "quickstart_sample.grib" if not os.path.exists(grib_filepath): print(f"Creating a dummy GRIB file '{grib_filepath}' for quickstart.") try: # Create a basic GRIB message from a sample. # This requires the eccodes sample data to be accessible. # If ECCODES_SAMPLES_PATH is not set, this might fail. gid = eccodes.codes_grib_new_from_samples("GRIB2") eccodes.codes_set(gid, "discipline", 0) # Meteorology eccodes.codes_set(gid, "parameterCategory", 0) # Temperature eccodes.codes_set(gid, "parameterNumber", 0) # Temperature (K) eccodes.codes_set_array(gid, "values", [273.15, 274.15, 275.15]) # Dummy data with open(grib_filepath, 'wb') as f: eccodes.codes_write(gid, f) eccodes.codes_release(gid) print(f"Successfully created a basic GRIB file: {grib_filepath}") except eccodes.CodesInternalError as e: print(f"Warning: Could not create a valid GRIB sample using eccodes ({e}).") print("Falling back to an empty dummy file. Quickstart may not show full functionality.") with open(grib_filepath, 'w') as f: f.write("DUMMY_FILE_CONTENT_NOT_GRIB") except Exception as e: print(f"An unexpected error occurred during GRIB sample creation: {e}") with open(grib_filepath, 'w') as f: f.write("DUMMY_FILE_CONTENT_NOT_GRIB") # --- End of Quickstart setup --- # Main Quickstart logic: Reading GRIB messages try: message_count = 0 with eccodes.GribFile(grib_filepath) as gf: print(f"\nOpened GRIB file: {grib_filepath}") for i, msg in enumerate(gf): message_count += 1 print(f" Processing Message {i+1}:") try: # Access common keys using the high-level interface centre = msg.get("centre", "N/A") param = msg.get("shortName", "N/A") level = msg.get("level", "N/A") date = msg.get("date", "N/A") time = msg.get("time", "N/A") print(f" Centre: {centre}, Parameter: {param}, Level: {level}, Date: {date}, Time: {time}") # Access values (can be a large array). Avoid printing all. values = msg.get("values", []) if values: print(f" First 5 values: {values[:min(5, len(values))]}") else: print(" No values found or dummy file used.") except eccodes.KeyError as e: print(f" Warning: Key not found in message: {e}") except Exception as e: print(f" An error occurred while processing message: {e}") if message_count >= 1: # Process only the first message for brevity break if message_count == 0: print(f"No GRIB messages found in {grib_filepath}. (Might be a dummy file or empty).") except eccodes.WrongElementException as e: print(f"\nError: '{grib_filepath}' is not a valid GRIB file or corrupted. Details: {e}") except FileNotFoundError: print(f"\nError: GRIB file '{grib_filepath}' not found.") except Exception as e: print(f"\nAn unexpected error occurred during GRIB file processing: {e}") finally: # Clean up the dummy file if os.path.exists(grib_filepath) and grib_filepath == "quickstart_sample.grib": os.remove(grib_filepath) print(f"Cleaned up dummy file: {grib_filepath}")
eccodes --version
Debug
Known issues
gotchaResource management: When using the low-level `codes` API (e.g., `codes_grib_new_from_file`), it's crucial to explicitly call `codes_release(handle)` and `codes_close_file(file_handle)` to prevent memory leaks and file descriptor exhaustion. Failure to do so is a common source of instability in long-running applications.
fix
Prefer using the high-level `GribFile` and `BufrFile` context managers (e.g., `with eccodes.GribFile(...) as gf:`) which handle resource cleanup automatically. If using the low-level API, ensure `codes_release()` and `codes_close_file()` are called in a `finally` block or context manager.
affects: All versions
gotchaMixing high-level and low-level APIs: The library offers both a direct Python binding to the C API (`eccodes.codes`) and a higher-level, more Pythonic interface (`GribFile`, `BufrFile`, `GribMessage`, `BufrMessage`). Mixing these paradigms within the same code path, especially regarding message handles, can lead to unexpected behavior or resource management issues.
fix
Choose one API style and stick to it for clarity and consistency. The high-level API is generally recommended for new development due to its ease of use and automatic resource management. Only use the low-level API when specific C-level functionality is required.
affects: All versions
breakingHigh-level BUFR API changes: The high-level BUFR interface has seen significant development and fixes across recent versions (e.g., 2.41.0, 2.44.0, 2.46.0). This means methods like `set` and `get` for BUFR data keys might have changed behavior or arguments between minor versions.
fix
Carefully review the release notes for BUFR-related changes when upgrading. Thoroughly test code interacting with the high-level BUFR API after any version update. Consult the official ECMWF eccodes-python documentation for the latest BUFR API usage patterns.
affects: 2.41.0 and later, particularly for BUFR users.
gotchaExternal C library dependency for custom builds: While `pip install eccodes` typically provides pre-built wheels that bundle the underlying `ecCodes` C library, building from source or using the `--no-binary eccodes` option requires a system-level installation of the `ecCodes` C library and its development headers. Failure to meet these dependencies will result in compilation errors.
fix
For most users, relying on the pre-built wheels provided on PyPI is the simplest solution. If building from source is necessary, ensure `ecCodes` is installed on your system (e.g., via `conda install -c conda-forge eccodes-cpp` or your system package manager) and that its development files are discoverable during the `pip install` process.
affects: All versions when building from source or using `--no-binary`.
Errors
Common errors & fixes
RuntimeError: Cannot find the ecCodes library!
The Python `eccodes` package, which provides bindings, cannot locate the underlying ECMWF ecCodes C library on your system. This often happens if the C library is not installed, not in a standard path, or if environment variables are not correctly set.
fix
Ensure the ecCodes C library is installed. On Linux/macOS, if installed via `conda`, use `conda install -c conda-forge eccodes`. If using `pip` from version 2.37.0 onwards, the binary library is often bundled, but issues can still arise. For debugging, set the environment variable `ECCODES_PYTHON_TRACE_LIB_SEARCH=1` before importing `eccodes` to see where it's looking. If installed separately, ensure `LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS) points to the directory containing the ecCodes shared library.
eccodes.CodesInternalError: Key/value not found
You are attempting to access or set a GRIB/BUFR key that does not exist in the message, is misspelled, or is not applicable to the specific GRIB/BUFR edition or template of the message being processed.
fix
Verify the exact key name and its applicability to your GRIB/BUFR message using tools like `grib_ls` or `grib_dump` (from the ecCodes command-line tools) or by iterating through keys in the `eccodes` Python interface. Ensure correct casing and spelling. For example:
```python
import eccodes

with open('your_grib_file.grib', 'rb') as f:
    while True:
        msgid = eccodes.codes_grib_new_from_file(f)
        if msgid is None:
            break
        # Correct key name, e.g., 'paramId'
        try:
            param_id = eccodes.codes_get_long(msgid, 'paramId')
            print(f"paramId: {param_id}")
        except eccodes.CodesInternalError as e:
            print(f"Error accessing key: {e}")
        eccodes.codes_release(msgid)
```
ECCODES ERROR : Unable to find boot.def. Context path=/path/to/eccodes/definitions.
The `eccodes` library cannot find its definition files, which are crucial for decoding and encoding GRIB and BUFR messages. This usually points to an incorrect installation or an improperly set `ECCODES_DEFINITION_PATH` environment variable.
fix
Ensure the `eccodes` library and its definitions are correctly installed. If using `conda`, install both `eccodes` and `cfgrib` (which often handles definition paths). If installing from source or encountering this error, set the `ECCODES_DEFINITION_PATH` environment variable to the directory where the `definitions` and `samples` subdirectories of ecCodes are located. You can also run `python -m eccodes selfcheck` to diagnose the issue.
AttributeError: module 'eccodes' has no attribute 'get'
The `eccodes` Python interface closely mirrors the C API, which uses specific functions for getting/setting different data types (e.g., `codes_get_long`, `codes_get_string`, `codes_set_double`). There isn't a generic `eccodes.get()` or `eccodes.set()` method directly on the module or handle object in the C-like API.
fix
Use the type-specific `codes_get_*` and `codes_set_*` functions provided by the `eccodes` module. For example, to get a long integer key, use `eccodes.codes_get_long(msgid, 'paramId')`, and for a string, use `eccodes.codes_get_string(msgid, 'shortName')`. Similarly for setting values, use `eccodes.codes_set_long()` or `eccodes.codes_set_string()`.
Upgrade
Version history
2.48.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
18
Resources
eccodes — pip install eccodes · libregistry