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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.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
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).
fixFor 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.
fixEnsure 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.
fixIf 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.