Registry / data / rio-cogeo

rio-cogeo

JSON →
library7.0.2pypypi✓ verified 85d ago

rio-cogeo is a Rasterio plugin that streamlines the creation and validation of Cloud Optimized GeoTIFF (COG) files. It intelligently handles critical COG specifications, including internal tiling, overview generation, and metadata ordering, ensuring geospatial data is optimized for efficient cloud storage and rapid web-based access. The library is actively maintained with consistent releases, serving as a vital tool in modern geospatial data pipelines.

pip install rio-cogeo
INSTALL
IMPORT
SIG · RIO-COGEO
R
rio-cogeo
datapythonv7.0.2
Install
7.4s avg
Import
Disk
230MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.0.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.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 7.4s · import 0.000s · 233MB
230MB installed
● package 230MB
Code
Verified usage

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

cog_translate
from rio_cogeo.cogeo import cog_translate
Primary function for programmatic COG creation.
cog_profiles
from rio_cogeo.profiles import cog_profiles
Used to access predefined COG profiles for compression and tiling options.
cog_validate
from rio_cogeo.cogeo import cog_validate
For programmatic validation of COG files.

rio-cogeo can be used via its command-line interface (CLI) or directly through its Python API. The CLI (prefixed with `rio cogeo`) is often the simplest for common tasks like creating or validating COGs. The Python API offers more granular control for integration into custom scripts. This example demonstrates both a dummy file creation for testing and a programmatic COG translation, showing how to leverage `cog_translate` and `cog_profiles`.

# Create a dummy GeoTIFF for demonstration import rasterio import numpy as np from rasterio.transform import from_bounds width, height = 1000, 1000 transform = from_bounds(-10, 40, 10, 60, width, height) with rasterio.open( 'input.tif', 'w', driver='GTiff', height=height, width=width, count=1, dtype=np.uint8, crs='EPSG:4326', transform=transform, ) as dst: dst.write(np.zeros((height, width), dtype=np.uint8), 1) print("Created input.tif") # --- Using rio-cogeo CLI --- # Create a COG with DEFLATE compression (default profile) # This command is run from the shell, not directly in Python # import os # os.system("rio cogeo create input.tif output_deflate.tif") # print("Created output_deflate.tif") # Create a COG with JPEG profile, add internal mask, and select first 3 bands # os.system("rio cogeo create input.tif output_jpeg.tif -b 1 --add-mask --cog-profile jpeg") # print("Created output_jpeg.tif") # Validate a COG # os.system("rio cogeo validate output_deflate.tif") # print("Validated output_deflate.tif") # Example of programmatic COG creation from rasterio.io import MemoryFile from rio_cogeo.cogeo import cog_translate from rio_cogeo.profiles import cog_profiles # Use a local file path for input src_path = 'input.tif' output_path_programmatic = 'output_programmatic.tif' dst_profile = cog_profiles.get("deflate") with rasterio.open(src_path) as src_dataset: cog_translate( src_path, output_path_programmatic, dst_profile, config=dict(GDAL_NUM_THREADS='ALL_CPUS', GDAL_TIFF_OVR_BLOCKSIZE='128'), overview_resampling='nearest', web_optimized=False, in_memory=False, quiet=True, # For real usage, consider `dst_kwargs` for profile overrides or `resampling` for overviews ) print(f"Created {output_path_programmatic} programmatically.") # Clean up dummy files import os os.remove('input.tif') os.remove('output_programmatic.tif') # os.remove('output_deflate.tif') # Uncomment if running CLI examples # os.remove('output_jpeg.tif') # Uncomment if running CLI examples
rio --version
Debug
Known issues
breakingPython 3.10 support was removed in rio-cogeo version 7.0.0. Users on Python 3.10 must upgrade their Python environment to 3.11 or newer.
fix
Upgrade Python to version 3.11 or later. (e.g., `conda install python=3.11` or rebuild virtual environment).
affects: >=7.0.0
gotchaUsing internal nodata values with lossy compression profiles (e.g., `jpeg`, `webp`) is generally not recommended as it can lead to unexpected visual artifacts or data loss around nodata regions. Internal masking or using an alpha band is often a more robust approach for lossy formats.
fix
For lossy compressed COGs, prefer using the `--add-mask` option to create an internal bitmask, or ensure your input has an alpha band. Avoid `nodata` for such profiles where possible, or use lossless compression like `deflate`.
affects: All
gotchaWhen using the `--web-optimized` option without a nodata value, an alpha band, or an internal mask in the input dataset, the output COG may contain padded areas filled with black (0) data. This can lead to larger file sizes than expected.
fix
Ensure your input dataset has a proper nodata value, an alpha band, or use the `--add-mask` option when creating web-optimized COGs to prevent unintended padding with zero values.
affects: All
gotchaThe `rio_cogeo.cog_translate` function or `rio cogeo create` CLI command might produce output raster pixel values that differ from the input if `ColorInterp` metadata is incorrectly defined or if lossy compression is applied and comparisons are made at overview resolutions (which are resampled).
fix
Verify `ColorInterp` metadata in your source TIFFs (e.g., using `gdalinfo`). If using lossy compression, compare pixel values at the native resolution. For exact value preservation, use lossless compression profiles like `deflate` or `zstd`.
affects: All
Errors
Common errors & fixes
ERROR 1: blocksize exceeds raster width (or height)
This error typically occurs with very small input GeoTIFFs (e.g., some JPEG2000 preview files) where the internal block size defined in the source raster is larger than the actual band dimensions (width or height).
fix
For such small rasters, consider using `rasterio.shutil.copy` directly without `rio-cogeo`, or if using `rio-cogeo` via the API, manually set a smaller `blocksize` in `dst_profile['blockxsize']` and `dst_profile['blockysize']` (e.g., 256 or 128) for the output.
Command 'rio cogeo' not found (or similar CLI execution error)
The `rio` command-line interface is part of `rasterio`, and `cogeo` is a subcommand added by `rio-cogeo`. This error indicates that either `rasterio` or `rio-cogeo` is not installed, or the environment's `PATH` does not include the location of the `rio` executable.
fix
Ensure both `rasterio` and `rio-cogeo` are installed in your active Python environment: `pip install rasterio rio-cogeo`. If in a virtual environment, ensure it is activated.
ERROR 1: Freezing Dataset, not enough space for overviews.
This error occurs when `rio-cogeo` attempts to create internal overviews or otherwise reorganize the GeoTIFF structure, but the output file system (or memory if processing in-memory) does not have sufficient contiguous space for the operation.
fix
If working with large files, ensure you have ample free disk space in the output directory. If using `in_memory=True` (programmatically), you may be running out of RAM. Try setting `in_memory=False` or reducing the number of overview levels.
Upgrade
Version history
7.0.2latest on PyPI · released Mar 27, 2026
Audit
Dependencies
rasteriorequiredrio-cogeo is a plugin for Rasterio, extending its command-line interface and API for COG functionalities.
GDALrequiredUnderpins Rasterio and rio-cogeo for all geospatial data operations. GDAL >= 2.3 is recommended.
morecantilerequiredUsed for tile matrix set operations and web-optimized COG creation.
Agent activity
79 hits · last 30 days
node
72
Bingbot
1
OpenAI (training)
1
Resources
rio-cogeo — pip install rio-cogeo · libregistry