{"id":5917,"library":"eccodeslib","title":"eccodeslib Python Interface to ecCodes","description":"eccodeslib provides the official Python interface to ECMWF's ecCodes C library, allowing users to encode and decode WMO FM-92 GRIB (editions 1 and 2), BUFR (editions 3 and 4), and GTS abbreviated header messages. It enables reading and writing meteorological data files, accessing keys and values, and iterating over messages. The current version is 2.46.2.19, with releases closely tied to the underlying ecCodes C library development.","status":"active","version":"2.46.2.19","language":"en","source_language":"en","source_url":"https://github.com/ecmwf/eccodes-python","tags":["GRIB","BUFR","meteorology","ECMWF","weather data","data decoding"],"install":[{"cmd":"pip install eccodeslib","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"eccodeslib 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.","package":"ecCodes C library","optional":false}],"imports":[{"note":"The primary module for all ecCodes functions.","symbol":"eccodes","correct":"import eccodes"}],"quickstart":{"code":"import eccodes as ec\nimport os\n\n# --- This quickstart requires a sample GRIB file. ---\n# You can download sample GRIB files from ECMWF's website or find them in\n# ecCodes/eccodes-python test directories, e.g., 'tests/data/regular_latlon_surface.grib2'.\n# Replace 'path/to/sample.grib' with the actual path to your GRIB file.\n# For example, a small GRIB file could be 'https://github.com/ecmwf/eccodes/blob/develop/tests/data/sample.grib2'.\n\nGRIB_FILE_PATH = os.environ.get('ECCODES_SAMPLE_GRIB_PATH', 'path/to/sample.grib')\n\ntry:\n    print(f\"Attempting to read GRIB file: {GRIB_FILE_PATH}\")\n    message_count = 0\n    with open(GRIB_FILE_PATH, 'rb') as f:\n        while True:\n            # Get a new GRIB message handle from the file\n            handle = ec.codes_handle_new_from_file(f, ec.CODES_PRODUCT_GRIB)\n            if handle is None:\n                break # End of file\n\n            message_count += 1\n            # Access common keys\n            short_name = ec.codes_get(handle, 'shortName')\n            param_id = ec.codes_get_long(handle, 'paramId')\n            date = ec.codes_get_long(handle, 'dataDate')\n            time = ec.codes_get_long(handle, 'dataTime')\n\n            print(f\"  Message {message_count}: shortName={short_name}, paramId={param_id}, Date={date}, Time={time}\")\n\n            # Release the handle to free memory\n            ec.codes_release(handle)\n\n    if message_count == 0:\n        print(\"No GRIB messages found in the file.\")\n    else:\n        print(f\"Successfully processed {message_count} GRIB messages.\")\n\nexcept FileNotFoundError:\n    print(f\"Error: GRIB file not found at '{GRIB_FILE_PATH}'. Please ensure the file exists or set ECCODES_SAMPLE_GRIB_PATH.\")\nexcept ec.CodesInternalError as e:\n    print(f\"Error processing GRIB file: {e}. Ensure ecCodes C library is installed and the GRIB file is valid.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Before `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`.","message":"The `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.","severity":"breaking","affected_versions":"All versions of eccodeslib."},{"fix":"Always 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.","message":"Failing 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.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Consult 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`.","message":"ecCodes 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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}