---
id: cogeo-mosaic
version: "9.2.0"
license: MIT License Copyright (c) 2019 Development Seed Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# cogeo-mosaic — CLI and Backends to work with MosaicJSON.

License: permissive · Maintenance: active · Downloads: 114.6K/mo

## What it is and what it does

cogeo-mosaic is a library for creating and querying mosaics of Cloud Optimized GeoTIFF (COG) files using the mosaicJSON specification. It provides multiple backend implementations (in-memory, file-based, HTTP, cloud storage) to store and retrieve mosaic metadata, enabling efficient spatial queries across large collections of geospatial imagery without loading entire datasets into memory.

The package integrates with rasterio and rio-tiler for geospatial operations, uses morecantile for tile matrix set support, and offers both a Python API and CLI tools. It supports multiple coordinate reference systems and tile matrix sets beyond the default Web Mercator, making it suitable for diverse geospatial workflows. Recent versions (9.0+) introduced breaking changes to backend APIs and mosaic information models to align with mosaicJSON 0.0.3 specification.

Use it for:

- Build searchable mosaics of satellite or aerial imagery stored as COGs in cloud storage (S3, Azure, GCS).
- Query which COG tiles intersect a given geographic point, bounding box, or tile coordinate.
- Serve dynamic tiles from a mosaic collection via a web service (commonly paired with TiTiler).
- Manage and organize large collections of geospatial rasters with metadata in mosaicJSON format.
- Convert between different tile matrix sets when working with non-Web-Mercator coordinate systems.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Creates and manages mosaics of Cloud Optimized GeoTIFF files according to the mosaicJSON specification, enabling efficient access to large collections of geospatial imagery.

Yes. The package is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem in geospatial workflows. The MIT license is permissive. Be aware of breaking changes in recent major versions (9.0+) if upgrading; review the changelog for API changes to backends and mosaic models.

## Install

pip install cogeo-mosaic
uv add cogeo-mosaic
poetry add cogeo-mosaic

## Installing cogeo-mosaic

Before you install: Low install friction with a pure-Python wheel. The package requires libgeos (via shapely) as a system dependency since version 5.0, but shapely wheels are available for most environments. Actively maintained with recent releases and Python 3.14 support.

License in practice: MIT License permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the license and copyright notice.

Quickstart:

pip install cogeo-mosaic

from cogeo_mosaic.backends import MemoryBackend
from cogeo_mosaic.models import MosaicJSON

mosaic_def = MosaicJSON(name="my_mosaic", tiles=[...])
with MemoryBackend(mosaic_def=mosaic_def) as mosaic:
    img, mask = mosaic.tile(0, 0, 0)

Requires libgeos system library (shapely wheels available for most platforms; manual installation needed on some systems).

Verify before relying:

- Whether httpx2 (the HTTP client switched to in 9.2.0) is a typo or intentional package name.
- Performance characteristics when working with very large mosaic collections.
- Specific cloud storage backend support beyond Azure, Google Cloud, and S3.

## Package facts

- License: MIT License Copyright (c) 2019 Development Seed Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 114.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

cloud optimized geotiff mosaic, mosaicjson creation, cog tile management, geospatial image mosaicing, raster mosaic backends, tile matrix set support, cog aggregation, geospatial, cloud-optimized-geotiff, tile-serving

[View on SkillFed](https://skillfed.io/packages/cogeo-mosaic) · [View on PyPI](https://pypi.org/project/cogeo-mosaic/)