{"id":1691,"library":"rasterio","title":"Rasterio","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/rasterio/rasterio","tags":["GIS","geospatial","raster","numpy","GDAL","remote sensing"],"install":[{"cmd":"pip install rasterio","lang":"bash","label":"Install Rasterio (may require GDAL pre-installation)"}],"dependencies":[{"reason":"Core C/C++ geospatial library for raster data. Must be installed separately on many systems or via specific Python wheels (e.g., from conda-forge).","package":"GDAL","optional":false},{"reason":"Fundamental library for array operations, used extensively by Rasterio for raster data representation.","package":"numpy","optional":false},{"reason":"Provides a 2D affine transformation matrix library, used for georeferencing in Rasterio.","package":"affine","optional":false}],"imports":[{"symbol":"rasterio","correct":"import rasterio"},{"symbol":"open","correct":"import rasterio\nsrc = rasterio.open('path/to/file.tif')"},{"symbol":"CRS","correct":"from rasterio.crs import CRS"}],"quickstart":{"code":"import rasterio\nimport numpy as np\nimport os\n\n# Create a dummy GeoTIFF for demonstration purposes\n# In a real application, you would open an existing file\ndummy_filepath = '/tmp/example_rasterio.tif'\n\n# Ensure the directory exists\nif not os.path.exists(os.path.dirname(dummy_filepath)):\n    os.makedirs(os.path.dirname(dummy_filepath))\n\nwith rasterio.open(\n    dummy_filepath,\n    'w',\n    driver='GTiff',\n    height=10,\n    width=10,\n    count=1,\n    dtype=rasterio.uint8,\n    crs='EPSG:4326',\n    transform=rasterio.transform.from_origin(0, 0, 1, 1),\n) as dst:\n    dst.write(np.zeros((10, 10), dtype=rasterio.uint8), 1)\n\n# --- Quickstart: Open and inspect a raster --- \ntry:\n    with rasterio.open(dummy_filepath) as src:\n        print(f\"Dataset profile: {src.profile}\")\n        print(f\"Number of bands: {src.count}\")\n        print(f\"Coordinate Reference System: {src.crs}\")\n        print(f\"Bounds: {src.bounds}\")\n\n        # Read the first band as a NumPy array\n        band1 = src.read(1)\n        print(f\"Shape of band 1: {band1.shape}\")\n        print(f\"Data type of band 1: {band1.dtype}\")\n\nexcept rasterio.errors.RasterioIOError as e:\n    print(f\"Error opening raster: {e}. Make sure '{dummy_filepath}' exists and is a valid raster.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# Clean up the dummy file\nif os.path.exists(dummy_filepath):\n    os.remove(dummy_filepath)","lang":"python","description":"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."},"warnings":[{"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.","message":"Rasterio 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+).","severity":"breaking","affected_versions":"1.5.0+"},{"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.","message":"Rasterio 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Behavioral 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.","severity":"gotcha","affected_versions":"<1.4.3 for masking, <1.4.2 for `reproject()` array shape"},{"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()`.","message":"Passing 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.","severity":"gotcha","affected_versions":"<1.4.3"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}