{"id":6428,"library":"pygrib","title":"pygrib","description":"Pygrib is a Python module designed for reading and writing GRIB (General Regularly-distributed Information in Binary form) files, which is the World Meteorological Organization (WMO) standard format for weather data. It provides a high-level interface to the ECMWF ECCODES C library, supporting both GRIB edition 1 and edition 2. The library is currently at version 2.1.8 and sees active development with regular releases.","status":"active","version":"2.1.8","language":"en","source_language":"en","source_url":"https://github.com/jswhit/pygrib","tags":["grib","meteorology","weather","data-processing","numerical-weather-prediction","netcdf"],"install":[{"cmd":"pip install pygrib","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install -c conda-forge pygrib","lang":"bash","label":"Anaconda/Conda"}],"dependencies":[{"reason":"Pygrib is a Python interface to the ECCODES C library. It is usually installed automatically by pip/conda, but manual installation and environment variable setup might be needed in some cases (e.g., building from source or specific system configurations).","package":"eccodes (C library)","optional":false},{"reason":"Required for array operations and data handling. Older versions of pygrib's setup.py could fail if numpy was not pre-installed.","package":"numpy","optional":false},{"reason":"Used for projection transformations. It's a key dependency.","package":"pyproj","optional":false},{"reason":"Only needed at build-time for compilation.","package":"cython","optional":true}],"imports":[{"symbol":"pygrib","correct":"import pygrib"}],"quickstart":{"code":"import pygrib\nimport os\n\n# Create a dummy GRIB file for demonstration purposes\n# In a real scenario, you would have an actual GRIB file.\n# This example can't create a GRIB file from scratch due to pygrib's limitations,\n# so we simulate reading one.\n\n# For actual usage, replace 'sample.grib2' with your file path.\n# If you don't have one, consider downloading a small sample GRIB file from a meteorological data source.\n# Example: A minimalist GRIB file (not functional for this code but demonstrates intent)\n\n# For this example, assume 'sample.grib2' exists and contains at least one message.\n# Placeholder for a real GRIB file path\ngrib_file_path = os.environ.get('GRIB_SAMPLE_PATH', 'sample.grib2')\n\n# Create a dummy file if it doesn't exist for the example to run without FileNotFoundError\nif not os.path.exists(grib_file_path):\n    print(f\"Warning: '{grib_file_path}' not found. Cannot run quickstart without a GRIB file.\\n\" \\\n          \"Please set the GRIB_SAMPLE_PATH environment variable or create 'sample.grib2'.\")\n    # Optionally create a minimal (non-functional) placeholder to prevent immediate crash\n    with open(grib_file_path, 'wb') as f:\n        f.write(b'GRIB-DUMMY-FILE') # Not a valid GRIB file, but prevents FileNotFoundError\n\n\ntry:\n    grbs = pygrib.open(grib_file_path)\n\n    # Read the first message\n    # .read() returns a list of messages, so we take the first element.\n    grb = grbs.read(1)[0]\n\n    print(f\"GRIB Message 1: {grb}\")\n    print(f\"Short Name: {grb.shortName}\")\n    print(f\"Parameter Name: {grb.name}\")\n    print(f\"Units: {grb.units}\")\n    print(f\"Valid Date: {grb.validDate}\")\n\n    # Get data values (as a numpy array)\n    data = grb.values\n    print(f\"Data shape: {data.shape}\")\n    print(f\"Data min/max: {data.min()}/{data.max()}\")\n\n    # Get latitudes and longitudes\n    lats, lons = grb.latlons()\n    print(f\"Latitudes shape: {lats.shape}, Longitudes shape: {lons.shape}\")\n\n    grbs.close()\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    if 'not a GRIB file' in str(e):\n        print(\"This often means the GRIB_SAMPLE_PATH points to an invalid or empty file.\")\n    if os.path.exists(grib_file_path) and os.path.getsize(grib_file_path) < 100: # heuristic for dummy file\n        print(\"The quickstart created a dummy file; please provide a real GRIB file for full functionality.\")","lang":"python","description":"This quickstart demonstrates how to open a GRIB file, read a message, and extract key information such as data values, latitudes, and longitudes. Note that a valid GRIB file is required to run this example effectively. The example includes a placeholder for a GRIB file path and a warning if a dummy file is used."},"warnings":[{"fix":"Consult the official pygrib installation documentation or `eccodes` documentation for your specific operating system. Ensure `ECCODES_DEFINITION_PATH` is correctly set if you encounter file not found errors related to definitions.","message":"Installation can be complex due to the underlying ECCODES C library dependency. On some systems (especially Windows or when building from source), manual installation of ECCODES and setting environment variables like `ECCODES_DEFINITION_PATH` (e.g., to `$CONDA_PREFIX/Library/share/eccodes/definitions`) might be necessary to avoid errors like 'boot.def cannot be found'. Pip/conda generally attempt to handle this automatically, but issues can arise.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using `conda`, explicitly request an older HDF5 version, for example: `conda install pygrib hdf5=1.8`.","message":"On Anaconda environments, compatibility issues with newer HDF5 library versions (e.g., 1.10.0) have caused `ImportError` due to linking problems with the `ecmwf_grib` dependency.","severity":"gotcha","affected_versions":"Older versions of pygrib (prior to 2.x), especially on Anaconda."},{"fix":"If creating GRIB files from scratch is needed, consider alternative libraries or tools that offer full GRIB creation capabilities, or start by modifying a minimal template GRIB file.","message":"Pygrib has limited capabilities for writing GRIB files. You can modify the contents (e.g., data values) of an *existing* GRIB message and write it, but you cannot create an entirely new GRIB file from scratch.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Before modifying `grb['values']`, store the original `grb['orderOfSpatialDifferencing']`. After setting new values, explicitly set `grb['orderOfSpatialDifferencing']` back to its original value: `original_order = grb['orderOfSpatialDifferencing']; grb['values'] = new_values; grb['orderOfSpatialDifferencing'] = original_order;`.","message":"When modifying GRIB2 message values (`grb['values']`), the `orderOfSpatialDifferencing` key might be reset to a default (e.g., 0), which can lead to the output GRIB2 file being considered 'unusable' by other GRIB tools (like `wgrib2`).","severity":"gotcha","affected_versions":"All versions when writing GRIB2"},{"fix":"If building from source and encountering Cython errors, try pinning Cython to an older, compatible version (e.g., `pip install 'Cython<3.0'`) or ensure you are using the latest `pygrib` version that includes fixes for newer Cython releases.","message":"Compatibility issues have been reported with newer versions of Cython (e.g., > 0.29 and >= 3.1), which might lead to build failures if Cython is not pinned to a compatible version during installation.","severity":"breaking","affected_versions":"Versions prior to `2.1.7` (where a fix for Cython >= 3.1 was likely introduced, based on typical release cycles for such issues)."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}