Install & Compatibility
Where this runs
tested against v7.9.6 · 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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 11.2s · import 0.000s · 327MB
329MB installed
● package 329MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Reader
✓ from rio_tiler.io import Reader
✗ from rio_tiler.io.cogeo import COGReader
The primary `COGReader` class was renamed to `Reader` in rio-tiler v4.0 and moved to `rio_tiler.io`.
STACReader
✓ from rio_tiler.io import STACReader
Used for reading data from STAC (SpatioTemporal Asset Catalog) items.
XarrayReader
✓ from rio_tiler.io import XarrayReader
Used for reading xarray DataArray objects. Requires `rio-tiler[xarray]` installation.
render
✓ from rio_tiler.utils import render
Utility function for rendering tile data to image formats (e.g., PNG, JPEG).
cmap
✓ from rio_tiler.colormap import cmap
Provides access to default and custom colormaps for rendering.
This quickstart demonstrates how to use the `rio_tiler.io.Reader` class to open a Cloud Optimized GeoTIFF (COG) from a URL, extract a specific Web Mercator tile (x, y, z), and then render it into a PNG image. The `ImageData` object returned by `tile()` contains both the raster data and its mask.
import os
from rio_tiler.io import Reader
from rio_tiler.utils import render
# Example Cloud Optimized GeoTIFF (COG) URL
# This URL is publicly available for testing
COG_URL = "https://sentinel-cogs.s3.amazonaws.com/sentinel-s2-l2a-cogs/29/R/KH/2020/2/S2A_29RKH_20200219_0_L2A/B04.tif"
# Define a tile (x, y, z) - example from documentation
x, y, z = 239, 220, 9
try:
with Reader(COG_URL) as src:
# Read a Web Mercator tile
img = src.tile(x, y, z)
# ImageData object holds the data (img.data) and mask (img.mask)
print(f"Tile shape: {img.data.shape}") # e.g., (1, 256, 256) for a single band
print(f"Mask shape: {img.mask.shape}") # e.g., (256, 256)
# Render the tile to a PNG buffer
buffer = img.render(img_format="PNG")
# Save the buffer to a file
output_filename = "output_tile.png"
with open(output_filename, "wb") as f:
f.write(buffer)
print(f"Tile saved to {output_filename}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure the COG_URL is accessible and GDAL is configured correctly.")
# For AWS S3 requester-pays buckets, you might need: os.environ['AWS_REQUEST_PAYER'] = 'requester'
Debug
Known issues
breakingThe primary reader class `COGReader` was renamed to `Reader` in rio-tiler v4.0. Additionally, the `rio_tiler.io.cogeo` submodule was deprecated in favor of `rio_tiler.io.rasterio` (though `Reader` is directly importable from `rio_tiler.io`).fixUpdate imports from `from rio_tiler.io.cogeo import COGReader` to `from rio_tiler.io import Reader` or `from rio_tiler.io.rasterio import Reader`.
affects: 4.0.0 and later
breakingSupport for Python 3.7 was removed in rio-tiler v4.0. Support for Python 3.9 and 3.10 was removed in v9.0.0.fixUpgrade your Python environment to Python 3.11 or newer.
affects: 4.0.0 and later (for Python 3.7), 9.0.0 and later (for Python 3.9, 3.10)
breakingIn rio-tiler v4.0, band names returned by methods like `.statistics()` or `.info()` are now prefixed with 'b' (e.g., 'b1', 'b2') instead of just the band number ('1', '2').fixAdjust code that accesses band names or metadata to expect the 'b' prefix.
affects: 4.0.0 and later
breakingThe way assets are specified in `STACReader`'s methods (e.g., `tile`) changed in v9.0.0b1. Instead of a string format like `"asset|indexes=1,2,3"`, it now requires a dictionary format: `{"name": "asset", "indexes": [1, 2, 3]}`.fixRefactor `STACReader` asset parameter usage to pass a list of dictionaries.
affects: 9.0.0b1 and later
gotchaReading from non-Cloud Optimized GeoTIFF (COG) raster formats (e.g., JPEG2000 Sentinel-2 data on AWS) can be inefficient due to numerous GET requests and large data transfers, impacting performance and cost.fixPrefer using Cloud Optimized GeoTIFFs (COGs) for optimal performance, especially with cloud-hosted data. If using non-COGs, be aware of potential performance implications.
affects: All versions
gotchaAccessing data from 'requester-pays' S3 buckets (e.g., some public datasets like Sentinel-2 on AWS) will fail with 'Failed to connect' or similar errors if not configured correctly.fixSet the `AWS_REQUEST_PAYER` environment variable to `"requester"` before making requests: `os.environ['AWS_REQUEST_PAYER'] = 'requester'`.
affects: All versions
Errors
Common errors & fixes
CPLE_AppDefinedError: Failed to connect to 169.254.169.254 port 80: Connection refused (or similar network connection error when using old `rio_tiler.sentinel2` module)
Attempting to use deprecated mission-specific modules (like `rio_tiler.sentinel2`) which might try to access old or removed public dataset URLs, or misconfigured AWS access for requester-pays buckets.
fixFor public datasets, use the `rio-tiler-pds` plugin. For generic COGs, use `rio_tiler.io.Reader`. Ensure `AWS_REQUEST_PAYER='requester'` is set in the environment if accessing requester-pays S3 buckets.
AttributeError: 'COGReader' object has no attribute 'tile' (or similar method missing from COGReader)
This error typically occurs when using code written for rio-tiler versions prior to 4.0, where the main class was `COGReader`, but in a v4.0+ environment where it has been renamed to `Reader` and its methods might have changed or been reorganized.
fixUpdate your code to import `Reader` from `rio_tiler.io` and adjust method calls if necessary, following the v4.0 migration guide.
ValueError: Dataset does not have rioxarray spatial dimensions (or 'Dataset does not have rioxarray bounds')
When using `rio_tiler.io.XarrayReader`, the input `xarray.DataArray` or `xarray.Dataset` must have a defined Coordinate Reference System (CRS) and spatial dimensions (X, Y or longitude, latitude) along with their bounds.
fixEnsure your xarray object has proper geospatial metadata, including `crs`, `x_dim`, `y_dim`, and `bounds`. You might need to use `rioxarray` to add or verify these attributes before passing the data to `XarrayReader`.
Upgrade
Version history
9.2.1latest on PyPI · released Jun 12, 2026
Audit
Dependencies
rasteriorequiredCore dependency for raster data I/O.
GDALrequiredUnderlying geospatial library, required by Rasterio.
morecantileoptionalUsed for TileMatrixSet (TMS) grids, enabling support for various projections.
typing-extensionsoptionalRequired for Python versions < 3.15.
xarrayoptionalOptional dependency for the XarrayReader, to work with xarray DataArray objects.