Registry / aws / rio-tiler

rio-tiler

JSON →
library9.2.1pypypi✓ verified 88d ago

rio-tiler is an active Python library that provides a user-friendly plugin for Rasterio, designed to read raster datasets efficiently. It acts as a wrapper around Rasterio and GDAL, facilitating dynamic slippy map tile creation and comprehensive data reading from various sources, including local files, HTTP, AWS S3, and Google Cloud Storage. The library is currently at version 9.0.6 and maintains a frequent release cadence, with both minor and major versions introducing new features and breaking changes.

pip install rio-tiler
INSTALL
IMPORT
SIG · RIO-TILER
R
rio-tiler
awspythonv9.2.1
Install
11.2s avg
Import
—
Disk
329MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
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
musl
py 3.10–3.940 runs
build_error
glibc
py 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`).
fix
Update 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.
fix
Upgrade 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').
fix
Adjust 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]}`.
fix
Refactor `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.
fix
Prefer 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.
fix
Set 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.
fix
For 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.
fix
Update 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.
fix
Ensure 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.
Agent activity
28 hits · last 30 days
node
26
OpenAI (training)
1
Resources
rio-tiler — pip install rio-tiler · libregistry