# rio-tiler: reading rasters by tile, feature and point

> rio-tiler is a Rasterio plugin that gives a raster dataset a spatial read API, so instead of computing window offsets yourself you ask for a slippy map tile, a bounding box, a GeoJSON feature or a point and get back data plus its metadata. It started as a tile cutter and became a general raster reader, and the pip install is short because the heavy lifting stays in GDAL.

**cogeotiff/rio-tiler** — User friendly Rasterio plugin to read raster datasets.

- Repository: https://github.com/cogeotiff/rio-tiler
- Website: https://cogeotiff.github.io/rio-tiler/
- Stars: 594 · Forks: 125
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/cogeotiff-rio-tiler

## From a tile cutter to a general raster reader

The README explains the arc of the project. rio-tiler was initially designed to create slippy map tiles from large raster data sources and render those tiles dynamically on a web map, and since version 2.0 many more helper methods were added to read data and metadata from any raster source supported by Rasterio or GDAL, including local and remote files via HTTP, AWS S3 and Google Cloud Storage. That is the honest summary of the design: a spatial read API over a raster, whether or not you intend to cut tiles from it.

The low-level position is stated plainly too. At the low level, rio-tiler is just a wrapper around the rasterio and GDAL libraries. The value is therefore in the interface, not in the I/O. Rasterio opens the dataset, GDAL does the decoding, and rio-tiler works out which window of the raster corresponds to the geographic region you asked for, handling reprojection on the way.

The project is BSD-3-Clause licensed, the author is Vincent Sarago, the default branch is main, and the recent releases are 9.4.12, 9.4.11 and 9.4.10, all in the first week of October 2026, with the last push to the repository on 2026-10-22.

## Reader, and the four read methods that define the API

The entry point is Reader, and the four read methods are the shape of the whole library. The first feature is simply reading any dataset supported by GDAL or Rasterio.

```python
from rio_tiler.io import Reader

with Reader("my.tif") as image:
    print(image.dataset)  # rasterio opened dataset
    img = image.read()    # similar to rasterio.open("my.tif").read() but returns a rio_tiler.models.ImageData object
```

The difference from calling rasterio directly is the return type. The read returns a rio_tiler.models.ImageData object rather than a bare array, so the data and its metadata travel together.

The user friendly methods are the tile, part, feature and point reads.

```python
from rio_tiler.io import Reader

with Reader("my.tif") as image:
    img = image.tile(x, y, z)            # read mercator tile z-x-y
    img = image.part(bbox)               # read the data intersecting a bounding box
    img = image.feature(geojson_feature) # read the data intersecting a geojson feature
    img = image.point(lon,lat)           # get pixel values for a lon/lat coordinates
```

A tile request is in slippy map coordinates, a part request takes a bounding box in the dataset's own coordinate system, a feature request takes a GeoJSON geometry, and a point request takes longitude and latitude and returns the pixel values under it. That last one is the method people reach for when they want a value rather than an image, for instance a temperature at a location from a climate raster.

## Per-read options, nodata and the mosaic helper

Reading options are passed per call, which is what makes the API composable. The example in the README sets a nodata value on a tile read.

```python
from rio_tiler.io import Reader

with Reader("my.tif") as image:
    img = image.tile(x, y, z, nodata=-9999) # read mercator tile z-x-y
```

Mosaicking is a separate namespace, and the shape is worth noticing because it does not assume a particular reader. You write a reader function and pass it in.

```python
from rio_tiler.io import Reader
from rio_tiler.mosaic import mosaic_reader

def reader(file, x, y, z, **kwargs):
    with Reader(file) as image:
        return image.tile(x, y, z, **kwargs)

img, assets = mosaic_reader(["image1.tif", "image2.tif"], reader, x, y, z)
```

The function returns both the merged image and the list of assets that contributed to it, so a caller can tell which source contributed which pixel. That is the kind of detail that matters in a mosaic, where the provenance of a pixel is often the question being asked.

There is also native support for multiple TileMatrixSet through the morecantile library, so the grid does not have to be Web Mercator.

```python
import morecantile
from rio_tiler.io import Reader

# Use EPSG:4326 (WGS84) grid
wgs84_grid = morecantile.tms.get("WorldCRS84Quad")
with Reader("my.tif", tms=wgs84_grid) as src:
    img = src.tile(1, 1, 1)
```

## STAC, Xarray and non-geographic images

Three specialisations cover the cases a plain Reader does not. STACReader reads a STAC item and works on its assets, including reading a tile from one asset and merging data across several assets with per-asset band selection.

```python
from rio_tiler.io import STACReader

with STACReader("item.json") as stac:
    print(stac.assets)  # available asset
    img = stac.tile(  # read tile for asset1 and indexes 1,2,3
        x,
        y,
        z,
        assets="asset1",
        indexes=(1, 2, 3),  # same as asset_indexes={"asset1": (1, 2, 3)},
    )
```

XarrayReader, marked as available from version 4.0, takes a data array rather than a file path, which is how you read a zarr store through the same tile interface.

```python
import xarray
from rio_tiler.io import XarrayReader

ds = xarray.open_dataset(
    "https://pangeo.blob.core.windows.net/pangeo-public/daymet-rio-tiler/na-wgs84.zarr/",
    engine="zarr",
    decode_coords="all",
    consolidated=True,
)
da = ds["tmax"]
with XarrayReader(da) as dst:
    print(dst.info())
    img = dst.tile(1, 1, 2)
```

That reader needs optional dependencies, installed with pip install rio-tiler["xarray"]. And ImageReader, also from 4.0, handles a non-geo image such as a JPEG, with tile, part and point reads, and the README notes it also works with properly geo-referenced raster datasets.

## Installation, and what the dependency list tells you

The pip install is two commands, one of them just to bring pip up to date.

```bash
python -m pip install -U pip
python -m pip install -U rio-tiler
```

Or from source.

```bash
git clone https://github.com/cogeotiff/rio-tiler.git
cd rio-tiler
python -m pip install -U pip
python -m pip install -e .
```

The runtime dependencies in the project metadata describe what this library is sitting on. affine and numpy for the array and geometry work, rasterio 1.5.1 or newer for the dataset access, morecantile between 5.0 and 8.0 for the tile matrix sets, pydantic 2 for the data model, pystac for the STAC support, httpx2 for the HTTP paths to remote data, cachetools, numexpr and color-operations. The Python floor is 3.12, with classifiers for 3.12, 3.13 and 3.14.

So the install pulls in GDAL through Rasterio, which is a compiled dependency in most environments, and that is the real cost of adopting this library rather than reading the file yourself. The dev group shows the shape of the test environment, with pytest, xarray and rioxarray for the Xarray reader, boto3 for the S3 paths, and zarr and obstore for the experimental backends, plus separate performance and docs groups that pull in pytest-benchmark, tilebench, mkdocs and mkdocstrings.

## Where the plugins split off, and what the implementations are

Two things have been moved out of the core package, and the first is a change you will notice if you follow older tutorials. rio-tiler v1 included several helpers for reading popular public datasets such as Sentinel 2, Sentinel 1, Landsat 8 and CBERS from cloud providers, and that functionality is now in a separate plugin, rio-tiler-pds, which the README describes as enabling easier access to more public datasets. The second is rio-tiler-mvt, for creating Mapbox Vector Tiles from raster sources.

The implementations section names the projects built on the library. titiler is a lightweight Cloud Optimized GeoTIFF dynamic tile server, and cogeo-mosaic creates mosaics of Cloud Optimized GeoTIFF based on the library. The distinction between rio-tiler and titiler is the one to hold on to: rio-tiler is a Python library you call from your own code, and titiler is a server you run that exposes tiles over HTTP.

The documentation lives at cogeotiff.github.io/rio-tiler/, the source at github.com/cogeotiff/rio-tiler, the package is on PyPI and on conda-forge, and the examples are runnable in a browser through a Binder link, which is the quickest way to see the API without setting up a local environment.

## Where rio-tiler is the wrong answer

Three situations point elsewhere. The first is a project that wants to avoid the Rasterio and GDAL stack. The README says outright that at the low level this is just a wrapper around those two libraries, so a team with a constraint against native geospatial dependencies should look at a pure Python path, or at a different raster library entirely, rather than at rio-tiler.

The second is a workload that is not spatial. rio-tiler's value is entirely in mapping between geographic regions and raster windows, so if your data has no coordinate system, or your access pattern is a scan of the whole file, then the extra layer of abstraction buys nothing and the wrapper around Rasterio is the more direct route. The non-geo ImageReader exists for images that carry no georeferencing, but it is a convenience rather than a reason to adopt the library.

The third is a team that wants vector tiles or a full tile service out of the box, where rio-tiler is the wrong layer. That is rio-tiler-mvt for the format and titiler for the service, and the README points at both. The honest framing is that rio-tiler is a well-designed convenience layer over a stack you were going to install anyway, and its value is real but bounded by that stack's reach.

## Conclusion

rio-tiler fits a Python geospatial developer who already uses Rasterio and GDAL and wants windowed reads that respect projection, bounds and nodata, or who needs STAC assets and multi-resolution tiling in the same code. It does not fit a workflow that avoids Rasterio and GDAL, since the README is explicit that at the low level it is just a wrapper around them, and it does not fit a repository that cannot take a native GDAL stack. Before you adopt it, check the Python floor, because the project metadata requires 3.12 or newer, and look at the rio-tiler-pds plugin, because the v1 helpers for Sentinel and Landsat are no longer in the core package and have to be installed separately.

## FAQ

### What does rio-tiler do?

It is a user friendly Rasterio plugin to read raster datasets, initially designed to create slippy map tiles from large raster sources and render them dynamically on a web map. Since version 2.0 it has added helper methods to read data and metadata from any raster source supported by Rasterio or GDAL, including local and remote files over HTTP, AWS S3 and Google Cloud Storage.

### How do I install rio-tiler?

With python -m pip install -U rio-tiler, after upgrading pip, or from source by cloning the repository and running python -m pip install -e .. The project metadata requires Python 3.12 or newer, with classifiers for 3.12, 3.13 and 3.14.

### What read methods does rio-tiler provide?

The Reader class offers tile, part, feature and point reads. A tile read takes x, y, z in slippy map coordinates, part takes a bounding box, feature takes a GeoJSON feature, and point takes longitude and latitude and returns the pixel values underneath.

### Does rio-tiler support STAC and Xarray data?

Yes. STACReader reads a STAC item and works on its assets, with the option to read a tile from one asset or merge several assets with per-asset band selection. XarrayReader, available from version 4.0, reads an xarray data array and needs the optional dependencies installed with pip install rio-tiler["xarray"].

### Where did the Sentinel and Landsat helpers in rio-tiler go?

They are no longer in the core package. The README says rio-tiler v1 included helpers for reading public datasets such as Sentinel 2, Sentinel 1, Landsat 8 and CBERS from cloud providers, and that this functionality is now in a separate plugin, rio-tiler-pds. Vector tile creation moved to rio-tiler-mvt.

## Sources

- [cogeotiff/rio-tiler on GitHub](https://github.com/cogeotiff/rio-tiler)
- [License: BSD-3-Clause](https://github.com/cogeotiff/rio-tiler/blob/main/LICENSE)
- [Project website](https://cogeotiff.github.io/rio-tiler/)
- [README](https://github.com/cogeotiff/rio-tiler/blob/main/README.md)
- [Releases](https://github.com/cogeotiff/rio-tiler/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cogeotiff-rio-tiler