Registry / data / cogeo-mosaic

cogeo-mosaic

library9.2.0pypypi✓ verified 88d ago

A Python library for creating and managing Cloud Optimized GeoTIFF (COG) mosaics using MosaicJSON format. Version 9.1.0 requires Python >=3.11 and supports rio-tiler 7+. Active development with frequent releases.

data aws

pip install cogeo-mosaic

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · COGEO-MOSAIC

cogeo-mosaic

datapythonv9.2.0

Install

9.4s avg

Import

—

Disk

254MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.2.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.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.4s · import 0.000s · 256MB

254MB installed

● package 254MB

Code

Verified usage

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

MosaicJSON

✓ from cogeo_mosaic.mosaic import MosaicJSON

MosaicBackend

✓ from cogeo_mosaic.backends import MosaicBackend

STACBackend

✓ from cogeo_mosaic.backends.stac import STACBackend

Create and query a Cloud Optimized GeoTIFF mosaic using MosaicJSON.

from cogeo_mosaic.mosaic import MosaicJSON from cogeo_mosaic.backends import MosaicBackend # Create a simple mosaic from a list of COG URLs cogs = [ "https://example.com/cog1.tif", "https://example.com/cog2.tif", ] mosaic = MosaicJSON.from_urls(cogs) # Save to local file with MosaicBackend("mosaic.json", mosaic_def=mosaic) as backend: backend.write() # Open existing mosaic with MosaicBackend("mosaic.json") as backend: tile = backend.tile(0, 0, 0) print(tile.shape)

cogeo-mosaic --version

Debug

Known issues

breakingVersion 9.0.0 switched to rio-tiler 7.x and changed backend base class from `BaseMosaic` to `rio_tiler.mosaic.backend.BaseBackend`. Custom backends must update imports.

fix

Replace `from cogeo_mosaic.backends.base import BaseMosaic` with `from rio_tiler.mosaic.backend import BaseBackend`.

affects: >=9.0.0

breakingVersion 8.0.0 dropped support for Python <3.8 and rio-tiler <7.0.

fix

Upgrade Python to >=3.8 and rio-tiler to >=7.0.

affects: >=8.0.0

gotchaWhen using S3 backends, credentials must be configured via environment variables or boto3 session. The library does not auto-configure from ~/.aws/config.

fix

Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN (if needed) environment variables.

affects: all

deprecated`from cogeo_mosaic.backends.base import BaseMosaic` is deprecated in 9.0.0 and removed in later versions.

fix

Use `from rio_tiler.mosaic.backend import BaseBackend` instead.

affects: >=9.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cogeo_mosaic'

Package not installed or installed in wrong environment.

fix

Run `pip install cogeo-mosaic` in the correct Python environment.

AttributeError: module 'cogeo_mosaic' has no attribute 'MosaicJSON'

Incorrect import path; MosaicJSON is in cogeo_mosaic.mosaic.

fix

Use `from cogeo_mosaic.mosaic import MosaicJSON`.

TypeError: Cannot read properties of undefined (reading 'shape') / rio_tiler.errors.InvalidBandNames

Using tile() without specifying assets or expression, or tile index out of bounds.

fix

Provide valid tile indices (x, y, z) and optionally set `assets` parameter.

cogeo_mosaic.errors.InvalidMosaicError: 'mosaic' must be a valid MosaicJSON

Passing a dictionary or invalid JSON to MosaicBackend constructor.

fix

Use `MosaicJSON.from_urls()` or `MosaicJSON.from_features()` to create a MosaicJSON object first.

Upgrade

Version history

9.2.0latest on PyPI · released Jun 18, 2026

Audit

Dependencies

rio-tilerrequiredRequired for mosaic backends and image retrieval

rasteriorequiredRequired for COG support

aiobotocoreoptionalOptional for S3 backend

boto3optionalOptional for AWS integrations

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/developmentseed/cogeo-mosaic ↗

packagehttps://pypi.org/project/cogeo-mosaic/ ↗

homepagehttps://developmentseed.org ↗

docshttps://developmentseed.org/cogeo-mosaic/ ↗

changeloghttps://developmentseed.org/cogeo-mosaic/release-notes/ ↗