{"id":1700,"library":"rtree","title":"R-Tree Spatial Index for Python GIS","description":"Rtree is a Python library that provides an R-Tree spatial index, implemented as a ctypes wrapper around the high-performance libspatialindex C library. It enables efficient spatial querying capabilities such as nearest neighbor and intersection searches for multi-dimensional data. The library supports bulk loading, deletion, and disk serialization of indexes, making it a crucial tool for various GIS and geospatial data processing tasks. It is actively maintained with regular updates.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/Toblerity/rtree","tags":["GIS","spatial-index","R-tree","geospatial","spatial-query"],"install":[{"cmd":"pip install rtree","lang":"bash","label":"Install Rtree"}],"dependencies":[{"reason":"Rtree is a Python wrapper around the libspatialindex C library. While pre-compiled binary wheels for Rtree often bundle libspatialindex for common platforms (Windows, macOS, manylinux), some *nix users, particularly in specialized environments or when a suitable wheel isn't available, may need to manually install libspatialindex (version 1.8.5+) from source prior to installing Rtree.","package":"libspatialindex","optional":true}],"imports":[{"note":"The primary way to interact with Rtree is through the 'index' module, specifically the index.Index class.","symbol":"index","correct":"from rtree import index"}],"quickstart":{"code":"from rtree import index\n\n# Create an in-memory R-tree index\nidx = index.Index()\n\n# Insert some bounding boxes (id, (minx, miny, maxx, maxy))\n# Note: IDs are not enforced to be unique by Rtree itself\nidx.insert(0, (0, 0, 1, 1)) # Item with ID 0, bounds (0,0) to (1,1)\nidx.insert(1, (0.5, 0.5, 1.5, 1.5))\nidx.insert(2, (2, 2, 3, 3))\nidx.insert(3, (0.8, 0.8, 1.2, 1.2), obj={'name': 'Intersection Point'})\n\n# Query for intersections with a given bounding box\nsearch_bounds = (0.7, 0.7, 1.1, 1.1)\nhits = list(idx.intersection(search_bounds))\nprint(f\"IDs intersecting {search_bounds}: {hits}\")\n\n# Query for intersections and retrieve objects (if stored)\nhits_with_objects = list(idx.intersection(search_bounds, objects=True))\nprint(\"Items intersecting (with objects):\")\nfor item in hits_with_objects:\n    print(f\"  ID: {item.id}, Bounds: {item.bbox}, Object: {item.object}\")\n\n# Query for nearest neighbors\nnearest_point = (0.1, 0.1)\nnearest_items = list(idx.nearest(nearest_point, num_results=1))\nprint(f\"Nearest item to {nearest_point}: {nearest_items}\")","lang":"python","description":"This quickstart demonstrates how to create an in-memory R-tree index, insert spatial objects (represented by bounding boxes and optional associated data), and perform intersection and nearest-neighbor queries."},"warnings":[{"fix":"Upgrade to Python 3.9 or newer, or downgrade Rtree to a version compatible with your Python environment (e.g., Rtree <1.4.0 for Python 3.8).","message":"Python version requirements have increased over recent major versions. Rtree 1.0.0 required Python 3.7+, 1.1.0 required Python 3.8+, and 1.4.0 (the latest major release) requires Python 3.9+. Users on older Python versions will encounter installation or runtime errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure all references and import statements conform to `rtree` as the package name. Review any custom build scripts or highly integrated legacy code for potential conflicts.","message":"In version 1.4.0, the project and its build components were officially renamed to 'rtree'. While standard import `from rtree import index` remains stable, if any tooling or older scripts relied on previous naming conventions for internal components, they might require updates.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Implement external checks or a wrapper around `rtree.index.Index` to enforce uniqueness if necessary for your use case.","message":"Entries inserted into an R-tree index are not inherently unique, either by ID or by bounding box. If uniqueness is a requirement for your application, it must be managed externally before inserting entries into the Rtree index.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always be mindful of the `interleaved` property when constructing or querying an index and ensure your coordinate arrays match the expected format. It's recommended to explicitly set `interleaved=True` or `False` in the `Property` object if you deviate from the default.","message":"The coordinate ordering for all Rtree functions is sensitive to the index's `interleaved` data member. If `interleaved` is `False` (the default), coordinates must be `[xmin, xmax, ymin, ymax, ..., kmin, kmax]`. If `True`, they must be `[xmin, ymin, ..., kmin, xmax, ymax, ..., kmax]`. Incorrect ordering will lead to incorrect query results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use Rtree for fast spatial indexing and querying, but manage data integrity, persistence, and transactional requirements using a proper database system (e.g., PostGIS) or other robust data management solutions.","message":"Rtree is a wrapper for `libspatialindex`, which was not designed to be a full-fledged spatial database. It does not offer typical database integrity protections (e.g., transactions, recovery). While useful for certain applications, it should not be treated as a robust database solution.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}