This space gives an overview of the migration to GRIB edition 2, informs about the progress, and will be continuously updated.
It is complementary to the existing documentation at ECMWF and used to merge and link relevant information. Code and file examples will also be published here.

The space also contains a short introduction into GRIB editions 1 and 2 including the advantages of GRIB2 over GRIB1.

The information presented on this page is subject to further change. To receive notifications of any updates please "watch" this page (requires log in) or subscribe to the mailing list .

What will you find here?

We have prepared separate pages to refresh your knowledge about GRIB format, and for the information about new WMO parameters and the full list of ecCodes changes:

• The mapping of parameters in GRIB1 and GRIB2
• Migration to GRIB2 - changes to encoding of parameters
• Migration to GRIB2 - sample static dataset
• GRIB edition 2 template example for Product Definition Section
• Migration to GRIB2 - new in ecCodes
• Migration to GRIB2 - new WMO parameters
• About GRIB data format
• Migration to GRIB2 - changes in the MARS language

Anticipated timeline

ECMWF plans to introduce GRIB2 edition 2 encoding (GRIB2) for all of its ENS (including the control (ex-HRES) and analysis) and sub-seasonal forecast output in IFS cy50r2. This will be a technical cycle upgrade which will be scientifically equivalent to IFS cy50r1 but with all output provided in GRIB2 only. 

The estimated timeline for the migration to GRIB2 is as follows:

• Q3 2025: static test dataset in full GRIB2 available via ftp and on the HPC
• Q2 2026: test dataset in full GRIB2 available in MARS
• Q3 2026: test data in full GRIB2 available in dissemination (after IFS Cycle 50r1 implementation)
• Q1 2027: implementation of IFS Cycle 50r2; full GRIB2 data only

Changes in ecCodes

Changes in ecCodes for decoding

The user interaction with the GRIB2 files via ecCodes is in principle the same as in GRIB1 by using the paramId or shortName keys to select a message or other edition independent high-level keys like dataDate or level.

There are some changes in the specification of parameters which can be classified into the following categories:

• some parameters have a different paramId in GRIB2 than in GRIB1
• a paramId in GRIB2 needs to be complemented by an additional key, e.g., a layer, whereas in GRIB1 a single paramId was sufficient
• a paramId is split into two Id's (paramId + chemId)
• some parameters have a different unit than in the official WMO GRIB2 parameter definitions.
  

Decoders other than ecCodes must be extended by the new parameters and templates proposed to the WMO before they can decode the data. ecCodes must be linked to the libaec library to be able to decode CCSDS compressed GRIB2 fields and a new ecCodes version is needed, which includes the new parameter and template definitions.

Changes in ecCodes for encoding

Besides the mapping of parameters and creating new templates, GRIB2 also impacts workflows for encoding data:

• several additional keys have to be set besides the keys defined in the concepts for encoding 
• for some parameters it is necessary to define the Product Definition Template Number before they can be encoded

There will be changes in some parameters like for example for soil, ice, and snow parameters on layers. Instead of having a paramId for each layer in GRIB1, in GRIB2 there will be only a single paramId for each soil parameter on layers, which can be distinguished by the level information encoded in the message. This means that instead of using a paramId for Volumetric soil water layer 1 and another for Volumetric soil water layer 2, only a single paramId is used for Volumetric soil water, and users have additionally to choose the layer in their workflow.

Another example is a splitting of the paramId’s for chemical parameters into a paramId and a chemId. This allows for more flexibility in adding new or additional chemical species. 

Changes in the MARS language

MARS requests for some parameters will also be affected by the migration to GRIB2.  These will include:

• changes to the param keyword;

• changes for parameters archived with levtype=sol;

• changes for parameters archived with levtype=hl;
• addition of a new MARS keyword timespan for retrieval of parameters processed statistically over a time interval;

• addition of new MARS keywords chem and wavelength for retrieval of chemical species;

• changes to the GRIB packing type for GRIB2 parameters retrieved on a grid.

See Migration to GRIB2 - changes in the MARS language for further details.

Outlook

The design phase for the next edition 3 of GRIB has already started. The next edition 3 will bring improvements like a finer sub-division of the message into twelve sections and an extended template-based approach giving even more flexibility than is currently available in GRIB2. An example is the representation of parameters processed over the vertical dimension via a separate Vertical Domain Section, which can also be expanded via new templates. Such “total-column” parameters have to be listed in GRIB2 instead as specific parameters in the WMO parameter code table. The migration from GRIB2 to GRIB3 will be much smoother, since GRIB3 is a de facto extension/improvement/revision of the GRIB2 format.  This next step from edition 2 to edition 3 will still take several years. The expected user impact will be considerably smaller than for the transition from edition 1 to 2. The actual migration to GRIB2 is also a good opportunity to learn from user feedback and challenges experienced during the transition to tailor user-oriented proposals to be submitted to WMO as a potential part of the next migration to GRIB3.

Further reading

• Migration from GRIB1 to GRIB2: preparing ECMWF model output for the future - ECMWF Newsletter Number 175 - Spring 2023