grib2cog - GRIB2 to Cloud-Optimized GeoTIFF Converter

Convert GRIB2 files to Cloud-Optimized GeoTIFF (COG) format.

Features

• Format conversion: GRIB2 → Cloud-Optimized GeoTIFF (COG) in a single GDAL pass
• Smart message grouping: one COG per (variable, level), forecast times as bands
• Message filtering: select by variable short name, level, forecast step, or raw band index
• Advanced compression: deflate / lzw / jpeg with a configurable deflate level
• Performance tuning: configurable tile size, overview levels, resampling, and output dtype
• Reprojection: transform to any EPSG coordinate system during conversion
• Batch processing: convert directories (one subdirectory per input file), parallel across files
• Rich metadata: 18 metadata fields written to every output COG
• Config file: YAML defaults merged with CLI overrides

Requirements

• Python 3.9+
• GDAL ≥ 3.8 with Python bindings

Installation

Install GDAL first:

• macOS: brew install gdal
• Ubuntu/Debian: sudo apt-get install gdal-bin libgdal-dev
• Windows: use the OSGeo4W installer

Then install grib2cog:

pip install grib2cog

From source

git clone <repository-url>
cd grib2cog
pip install .

Quick Start

# Convert a file: one COG per (variable, level), forecast times as bands
grib2cog input.grib2 output/

# Convert only one variable
grib2cog input.grib2 output/ --short-name UGRD

# Filter by level and forecast step
grib2cog input.grib2 output/ --level 0-MSL --step 0,3

# Convert to a specific file (requires exactly one group)
grib2cog input.grib2 output/ugrd.tif --short-name UGRD --level 10-HTGL

# Whole file as one multi-band COG
grib2cog input.grib2 output/ --whole-file

# Batch convert a directory (one subdirectory per input file), 4 files in parallel
grib2cog input_dir/ output/ --threads 4

Command Line Options

Filters are case-insensitive; different filters AND together, comma-separated values within one filter OR together.

Output Path Rules

Configuration File

compression: "deflate"
zlevel: 6
tile_size: 512
output_type: null        # null = preserve source dtype

overviews:
  resampling: "nearest"
  levels: [2, 4, 8, 16]

projection:              # optional
  source: "EPSG:4326"
  target: "EPSG:3857"
  resampling_method: "nearest"

overwrite: false
skip_errors: true

metadata:
  source: ""             # override Source (auto-detected from GRIB if empty)
  offset: 0.0
  scale: 1.0
  unit: ""               # fallback unit (auto-detected from GRIB if empty)

Use with: grib2cog --config config.yaml input.grib2 output/

CLI options override config-file values.

COG Metadata

Each output COG carries 18 metadata fields:

License

MIT — see LICENSE.