Registry / data / rtree
library1.4.1pypypi✓ verified 27d ago

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.

pip install rtree
INSTALL
IMPORT
SIG · RTREE
R
rtree
datapythonv1.4.1
Install
1.6s avg
Import
158ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.1 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.160s · 23.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.156s · 20MB
20MB installed
● package 20MB
Code
Verified usage

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

index
from rtree import index
The primary way to interact with Rtree is through the 'index' module, specifically the index.Index class.

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.

from rtree import index # Create an in-memory R-tree index idx = index.Index() # Insert some bounding boxes (id, (minx, miny, maxx, maxy)) # Note: IDs are not enforced to be unique by Rtree itself idx.insert(0, (0, 0, 1, 1)) # Item with ID 0, bounds (0,0) to (1,1) idx.insert(1, (0.5, 0.5, 1.5, 1.5)) idx.insert(2, (2, 2, 3, 3)) idx.insert(3, (0.8, 0.8, 1.2, 1.2), obj={'name': 'Intersection Point'}) # Query for intersections with a given bounding box search_bounds = (0.7, 0.7, 1.1, 1.1) hits = list(idx.intersection(search_bounds)) print(f"IDs intersecting {search_bounds}: {hits}") # Query for intersections and retrieve objects (if stored) hits_with_objects = list(idx.intersection(search_bounds, objects=True)) print("Items intersecting (with objects):") for item in hits_with_objects: print(f" ID: {item.id}, Bounds: {item.bbox}, Object: {item.object}") # Query for nearest neighbors nearest_point = (0.1, 0.1) nearest_items = list(idx.nearest(nearest_point, num_results=1)) print(f"Nearest item to {nearest_point}: {nearest_items}")
Debug
Known issues
breakingPython 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.
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).
affects: >=1.0.0
breakingIn 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.
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.
affects: >=1.4.0
gotchaEntries 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.
fix
Implement external checks or a wrapper around `rtree.index.Index` to enforce uniqueness if necessary for your use case.
affects: All versions
gotchaThe 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.
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.
affects: All versions
gotchaRtree 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.
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.
affects: All versions
Errors
Common errors & fixes
RTreeError: Could not find libspatialindex_c.so (or .dll/.dylib).
The `rtree` Python package requires the `libspatialindex` C library to be installed on your system, and it cannot find it in the standard library paths.
fix
Install `libspatialindex` using your system's package manager (e.g., `sudo apt-get install libspatialindex-dev` on Debian/Ubuntu, `brew install spatialindex` on macOS, or follow instructions for Windows).
ModuleNotFoundError: No module named 'rtree'
The `rtree` Python package has not been installed in your current Python environment.
fix
Install the package using pip: `pip install rtree`.
ValueError: Not enough values in bounds for 2 dimensions
When inserting or deleting an item into a 2-dimensional R-tree index, the provided `bounds` tuple or list did not contain the expected four numeric values (`min_x, min_y, max_x, max_y`).
fix
Ensure the `bounds` argument is a sequence of `2 * dimensions` (e.g., 4 for 2D) numeric values representing `(minx, miny, maxx, maxy)`. For a point at `(x,y)`, use `(x, y, x, y)`.
RTreeError: Could not open index file. Error: 'No such file or directory'
When attempting to create or open a persistent R-tree index, the specified directory in the index path does not exist, or the path itself is invalid.
fix
Ensure that all parent directories for the specified index file path exist before initializing the `rtree.index.Index` with that path. Create them if necessary using `os.makedirs(os.path.dirname(index_path), exist_ok=True)`.
Upgrade
Version history
1.4.1latest on PyPI · released Aug 13, 2025
Audit
Dependencies
libspatialindexoptionalRtree 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.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
rtree — pip install rtree · libregistry