rasterio

library1.5.1pypypi✓ verified 27d ago

Rasterio provides fast and direct raster I/O for use with NumPy, built on top of GDAL. It's a fundamental library for reading, writing, and manipulating geospatial raster data in Python. Rasterio typically releases new versions in response to GDAL updates and Python version changes, with minor releases for bug fixes and new features.

data

pip install rasterio

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · RASTERIO

rasterio

datapythonv1.5.1

Install

5.2s avg

Import

—

Disk

191MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.4 · 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 5.2s · import 0.000s · 193MB

191MB installed

● package 191MB

Code

Verified usage

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

rasterio

✓ import rasterio

open

✓ import rasterio src = rasterio.open('path/to/file.tif')

CRS

✓ from rasterio.crs import CRS

Demonstrates how to open a raster dataset, access its metadata (profile, CRS, bounds), and read a specific band into a NumPy array. A dummy GeoTIFF is created for standalone execution.

import rasterio import numpy as np import os # Create a dummy GeoTIFF for demonstration purposes # In a real application, you would open an existing file dummy_filepath = '/tmp/example_rasterio.tif' # Ensure the directory exists if not os.path.exists(os.path.dirname(dummy_filepath)): os.makedirs(os.path.dirname(dummy_filepath)) with rasterio.open( dummy_filepath, 'w', driver='GTiff', height=10, width=10, count=1, dtype=rasterio.uint8, crs='EPSG:4326', transform=rasterio.transform.from_origin(0, 0, 1, 1), ) as dst: dst.write(np.zeros((10, 10), dtype=rasterio.uint8), 1) # --- Quickstart: Open and inspect a raster --- try: with rasterio.open(dummy_filepath) as src: print(f"Dataset profile: {src.profile}") print(f"Number of bands: {src.count}") print(f"Coordinate Reference System: {src.crs}") print(f"Bounds: {src.bounds}") # Read the first band as a NumPy array band1 = src.read(1) print(f"Shape of band 1: {band1.shape}") print(f"Data type of band 1: {band1.dtype}") except rasterio.errors.RasterioIOError as e: print(f"Error opening raster: {e}. Make sure '{dummy_filepath}' exists and is a valid raster.") except Exception as e: print(f"An unexpected error occurred: {e}") # Clean up the dummy file if os.path.exists(dummy_filepath): os.remove(dummy_filepath)

rio --version

Debug

Known issues

breakingRasterio 1.5.0 introduced significant minimum version requirements: Python 3.12+, GDAL 3.8+, and NumPy 2+. Older Rasterio versions have different requirements (e.g., 1.4.x required Python 3.10+, GDAL 3.6+).

fix

Ensure your environment meets these new minimums before upgrading to 1.5.0. If unable to upgrade dependencies, use an older Rasterio version (e.g., 1.4.x) that aligns with your environment.

affects: 1.5.0+

gotchaRasterio relies on an external GDAL C/C++ library. Installing GDAL (and its dependencies like PROJ and GEOS) can be complex and platform-dependent, often requiring specific system packages or conda environments.

fix

Consult the official Rasterio and GDAL documentation for platform-specific installation instructions (e.g., `conda install -c conda-forge rasterio`). Pre-built wheels for Rasterio often bundle GDAL, but direct system-level GDAL installation might be required for certain features or environments.

affects: All versions

gotchaBehavioral changes in masking and `reproject()`: Prior to 1.4.3, boundless, masked reads could erroneously mask 0-valued data. Also, `reproject()` in versions before 1.4.2 might not consistently return 2-D arrays.

fix

Upgrade to Rasterio 1.4.3 or newer to resolve erroneous masking and ensure consistent `reproject()` output. Always test masking and reprojection carefully when using older versions.

affects: <1.4.3 for masking, <1.4.2 for `reproject()` array shape

gotchaPassing an open dataset object to `rasterio.open()`: Prior to Rasterio 1.4.3, this common mistake could lead to unexpected crashes. It now raises a `TypeError` for safer error handling.

fix

Upgrade to Rasterio 1.4.3+ to receive a `TypeError` instead of a crash. Always ensure you are passing a file path or URL string, not an already open `rasterio.DatasetReader` object, to `rasterio.open()`.

affects: <1.4.3

Errors

Common errors & fixes

ERROR: Could not find a GDAL library or header file.

Rasterio is a Python wrapper for the GDAL C/C++ library, and its installation requires the underlying GDAL development files to be present and discoverable on your system during the build process.

fix

Install GDAL development libraries appropriate for your operating system (e.g., `sudo apt-get install libgdal-dev` on Linux, `brew install gdal` on macOS, or OSGeo4W on Windows) before attempting `pip install rasterio`. Alternatively, use `conda install -c conda-forge rasterio` for easier dependency management.

rasterio.errors.RasterioIOError: Read of raster band failed

This error typically indicates a problem reading the raster data, often due to a corrupted or malformed file, an unsupported internal data structure within the file, or an issue with the underlying GDAL drivers.

fix

Verify the integrity of the raster file, ensure it's a valid geospatial raster, and check if the GDAL installation linked with Rasterio supports the specific file format and compression used. Try opening the file with `gdalinfo` or another GIS software to confirm its validity.

rasterio.errors.CRSError: Invalid CRS definition

Rasterio or the underlying GDAL library could not parse or understand the provided Coordinate Reference System (CRS) string or object, often due to incorrect syntax or an unrecognized format.

fix

Provide a valid CRS definition using a standard format such as an EPSG code (e.g., `CRS.from_epsg(4326)`), a well-formed WKT string, or a `pyproj.CRS` object.

rasterio.errors.RasterioIOError: Attempt to create new tiff file with missing crs

When creating a new raster file, Rasterio requires both the `crs` (Coordinate Reference System) and `transform` (georeferencing affine transform) parameters to be provided to ensure the output file is properly georeferenced.

fix

Always include the `crs` and `transform` arguments when opening a new dataset in write mode (`'w'`), typically derived from an existing dataset or explicitly defined, for example: `with rasterio.open('output.tif', 'w', driver='GTiff', height=array.shape[0], width=array.shape[1], count=1, dtype=array.dtype, crs=source_dataset.crs, transform=source_dataset.transform) as dst:`

Upgrade

Version history

1.5.1latest on PyPI · released Aug 8, 2026

Audit

Dependencies

GDALrequiredCore C/C++ geospatial library for raster data. Must be installed separately on many systems or via specific Python wheels (e.g., from conda-forge).

numpyrequiredFundamental library for array operations, used extensively by Rasterio for raster data representation.

affinerequiredProvides a 2D affine transformation matrix library, used for georeferencing in Rasterio.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/rasterio/rasterio ↗

packagehttps://pypi.org/project/rasterio/ ↗

docshttps://rasterio.readthedocs.io/ ↗