Install & Compatibility
Where this runs
tested against v0.19.0 · 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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.0s · import 0.000s · 309MB
311MB installed
● package 311MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rioxarray
✓ import rioxarray
Importing `rioxarray` activates the `.rio` accessor on `xarray.DataArray` and `xarray.Dataset` objects. You don't typically import specific classes or functions directly from `rioxarray` for most common use cases.
Demonstrates how to create a simple xarray DataArray, assign geospatial metadata using the `.rio` accessor, and retrieve basic spatial properties like CRS, bounds, and resolution. It also includes a commented-out example of reprojection, a common geospatial operation.
import xarray as xr
import rioxarray # Enables the .rio accessor
import numpy as np
# Create a dummy DataArray for demonstration
# In a real scenario, you'd typically open a GeoTIFF like this:
# da = xr.open_dataarray("path/to/your/file.tif", engine="rasterio")
# Dummy data: a 2x2 grid representing a small geographic area
data = np.array([[10.1, 20.2], [30.3, 40.4]], dtype=np.float32)
coords = {
"y": [45.5, 45.0], # Example latitude (y-coordinate, usually decreasing)
"x": [-120.0, -119.5], # Example longitude (x-coordinate, usually increasing)
}
da = xr.DataArray(data, coords=coords, dims=("y", "x"), name="temperature")
# Assign geospatial metadata using the .rio accessor
# These properties are typically inferred automatically when opening a geospatial file.
da = da.rio.write_crs("EPSG:4326") # WGS84 Geographic CRS
da = da.rio.set_spatial_dims(x_dim="x", y_dim="y") # Explicitly set spatial dimensions
print(f"Original CRS: {da.rio.crs}")
print(f"Original Bounds: {da.rio.bounds()}")
print(f"Original Resolution: {da.rio.resolution()}")
print(f"Original Width: {da.rio.width}")
print(f"Original Height: {da.rio.height}")
# Example of a common operation: Reproject to a different CRS
# Note: This operation requires 'pyproj' to be installed. Some systems
# might also need GDAL for full functionality and performance.
# try:
# # Reproject to Web Mercator (EPSG:3857)
# reprojected_da = da.rio.reproject("EPSG:3857")
# print(f"\nReprojected CRS: {reprojected_da.rio.crs}")
# print(f"Reprojected Bounds: {reprojected_da.rio.bounds()}")
# print(f"Reprojected Resolution: {reprojected_da.rio.resolution()}")
# except ImportError:
# print("\nSkipping reprojection: 'pyproj' not installed. Install with 'pip install pyproj'.")
# except Exception as e:
# print(f"\nCould not reproject: {e}")
Debug
Known issues
gotchaMany `.rio` operations (e.g., `reproject`, `bounds`, `resolution`) explicitly require a Coordinate Reference System (CRS) to be set on the DataArray. If the CRS is missing, these operations will raise an error.fixAlways ensure your DataArray has a CRS set. When opening files, use `xr.open_dataarray(..., engine='rasterio')` to infer it. For in-memory arrays or when modifying, use `da.rio.write_crs(crs_string_or_object)`.
affects: All versions
breakingThe `rasterio.crs.CRS` object, which `rioxarray` uses, became immutable in `rasterio` version 1.2.x (a dependency for `rioxarray >= 0.20.0`). This means direct in-place modification of CRS attributes (e.g., `da.rio.crs['init'] = 'epsg:4326'`) will now raise an error.fixInstead of modifying, create a new `CRS` object or use `da.rio.write_crs()` to completely replace the CRS. For example, `new_crs = rasterio.crs.CRS.from_epsg(4326)` then `da.rio.write_crs(new_crs)`.
affects: rioxarray >= 0.20.0 (due to rasterio >= 1.2.0)
gotchaThere can be nuances in handling `_FillValue` from NetCDF/HDF and `nodata` from GeoTIFFs. `rioxarray` attempts to unify these under `da.rio.nodata`, but inconsistencies or unexpected behavior can arise, especially when merging datasets or after reprojection where new `NaN` values might be introduced.fixExplicitly set and manage nodata values using `da.rio.write_nodata()` or `da.rio.update_attrs(nodata=...)` for consistency. Be mindful of `NaN` values introduced by transformations and handle them appropriately.
affects: All versions
deprecatedThe `da.rio.set_crs()` method is deprecated. While it may still function in current versions, it is recommended to use `da.rio.write_crs()` for better clarity and future compatibility.fixReplace `da.rio.set_crs(...)` with `da.rio.write_crs(...)`.
affects: rioxarray >= 0.19.0
gotchaWhen opening non-geospatial-specific file formats (e.g., generic NetCDF, HDF files without explicit geospatial metadata), you must explicitly specify `engine='rasterio'` with `xr.open_dataarray` or `xr.open_dataset` for `rioxarray` to process them. Otherwise, `xarray`'s default engine will be used, and the `.rio` accessor might not be available or fully functional.fixAlways specify `engine='rasterio'` (e.g., `xr.open_dataarray('file.nc', engine='rasterio')`) when you intend `rioxarray` to handle the geospatial interpretation of a file. affects: All versions
Errors
Common errors & fixes
AttributeError: 'DataArray' object has no attribute 'rio'
The rioxarray library was not imported, preventing the `.rio` accessor from being registered with xarray DataArrays/Datasets.
fixAdd `import rioxarray` at the beginning of your Python script or notebook cell.
ValueError: CRS not found. Please set the CRS with rio.write_crs() or rio.set_crs().
The xarray DataArray or Dataset does not have a Coordinate Reference System (CRS) defined, which is required for geospatial operations like reprojection.
fixExplicitly set the CRS using `data_array.rio.write_crs('EPSG:4326')` or `data_array.rio.set_crs('EPSG:4326', inplace=True)` with the appropriate CRS. FileNotFoundError: [Errno 2] No such file or directory: 'your_image.tif'
The specified file path to the raster data is incorrect, the file does not exist at that location, or there are insufficient permissions to access it.
fixVerify the file path, ensure the file exists, and check file permissions. Use an absolute path or ensure the file is in the current working directory.
rasterio.errors.CRSError: Invalid CRS provided.
The Coordinate Reference System (CRS) string or object provided for reprojection or CRS setting is malformed, unrecognized, or syntactically incorrect.
fixEnsure the CRS string is a valid format (e.g., 'EPSG:4326', 'PROJ:foo', or a WKT string). Check for typos and refer to valid CRS specifications.
ValueError: x coordinates are not monotonic. rioxarray cannot infer resolution.
The xarray DataArray's spatial coordinates (e.g., 'x' or 'lon') are not ordered monotonically (either strictly increasing or strictly decreasing), preventing rioxarray from correctly determining the raster's resolution and spatial extent.
fixReorder the DataArray along the non-monotonic dimension using `data_array.sortby('x')` or `data_array.sortby('y')`. Upgrade
Version history
0.23.0latest on PyPI · released Jul 27, 2026
Audit
Dependencies
xarrayrequiredCore data structure for labeled arrays, which rioxarray extends.
rasteriorequiredBackend for reading, writing, and manipulating geospatial raster data.
pyprojoptionalRequired for Coordinate Reference System (CRS) transformations like `da.rio.reproject()`. Often installed automatically with `rasterio`.
daskoptionalEnables out-of-core and parallel processing for large datasets.