fastquadtree

fastquadtree

Rust-optimized quadtree with a clean Python API

👉 Check out the Docs: https://elan456.github.io/fastquadtree/

Why use fastquadtree

• Just pip install: prebuilt wheels for Windows, macOS, and Linux (no Rust or compiler needed)
• The fastest quadtree Python package (>10x faster than pyqtree)
• Clean Python API with no external dependencies and modern typing hints
• Support for inserting bounding boxes or points
• Fast KNN and range queries
• Optional object tracking for id ↔ object mapping
• Fast serialization to/from bytes
• Support for multiple data types (f32, f64, i32, i64) for coordinates
• 100% test coverage and CI on GitHub Actions
• Offers a drop-in pyqtree shim that is ~6.5x faster while keeping the same API

Examples

See examples of how fastquadtree can be used in the runnables section.

Install

pip install fastquadtree

from fastquadtree import QuadTree  # Point handling
from fastquadtree import RectQuadTree  # Bounding box handling
from fastquadtree import QuadTreeObjects  # Point handling with object tracking
from fastquadtree import RectQuadTreeObjects  # Bounding box handling with object tracking
from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (~6.5x faster while keeping the same API)

Benchmarks

fastquadtree outperforms all other quadtree Python packages, including the Rtree spatial index.

Library comparison

Summary (largest dataset, PyQtree baseline)

• Points: 500,000, Queries: 500
• Fastest total: fastquadtree at 0.067 s

Library	Build (s)	Query (s)	Total (s)	Speed vs PyQtree
fastquadtree (np)1	0.057	0.021	0.078	54.45×
fastquadtree2	0.060	0.189	0.249	17.04×
Shapely STRtree3	0.321	0.196	0.517	8.21×
fastquadtree (obj tracking)4	0.437	0.239	0.675	6.28×
Rtree	1.796	0.561	2.357	1.80×
nontree-QuadTree	1.275	1.272	2.547	1.67×
e-pyquadtree	2.144	1.507	3.650	1.16×
quads	3.001	1.171	4.172	1.02×
PyQtree	3.677	0.565	4.242	1.00×

See the benchmark section for details, including configurations, system info, and native vs shim benchmarks.

Quickstart

See the quickstart guide

API

See the full API

QuadTree(bounds, capacity, max_depth=None, dtype="f32")

• bounds — tuple (min_x, min_y, max_x, max_y) defines the 2D area covered by the quadtree
• capacity — max number of points kept in a leaf before splitting
• max_depth — optional depth cap. If omitted, the tree can keep splitting as needed
• dtype — data type for coordinates, e.g., "f32", "f64", "i32", "i64"

Key Methods

• insert(xy, id_=None) -> int

• query(rect) -> list[tuple[int, float, float]]

• nearest_neighbor(xy) -> tuple[int, float, float] | None

• delete(id, x, y) -> bool

For object tracking, use QuadTreeObjects instead. See the docs for more methods.

Geometric conventions

• Rectangles are (min_x, min_y, max_x, max_y).
• Containment rule is closed on the min edge and open on the max edge (x >= min_x and x < max_x and y >= min_y and y < max_y). This only matters for points exactly on edges.

Performance tips

• Choose capacity so that leaves keep a small batch of points. Typical values are 8 to 64.
• If your data is very skewed, set a max_depth to prevent long chains.
• For fastest local runs, use maturin develop --release.
• Use QuadTree when you only need spatial indexing. Use QuadTreeObjects when you need to store Python objects with your points.
• Refer to the Native vs Shim Benchmark for overhead details.

Pygame Ball Pit Demo

A simple demo of moving objects with collision detection using fastquadtree. You can toggle between quadtree mode and brute-force mode to see the performance difference.

See the runnables guide for setup instructions.

FAQ

Can I delete items from the quadtree? Yes! Use delete(id, x, y) to remove specific items. You must provide both the ID and exact location for precise deletion. This handles cases where multiple items exist at the same location. If you're using QuadTreeObjects, you can also use delete_by_object(obj) for convenient object-based deletion with O(1) lookup. The tree automatically merges nodes when item counts drop below capacity.

Can I store rectangles or circles? Yes, you can store rectangles using the RectQuadTree class. Circles can be approximated with bounding boxes. See the RectQuadTree docs for details.

Do I need NumPy installed? No, NumPy is a fully optional dependency. If you do have NumPy installed, you can use methods such as query_np and insert_many_np for better performance. Note that insert_many raises TypeError on NumPy input—you must use insert_many_np explicitly for NumPy arrays. The Rust core is able to handle NumPy arrays faster than Python lists, so there's a lot of time savings in utilizing the NumPy functions. See the Native vs Shim benchmark for details on how returing NumPy arrays can speed up queries.

# Using Python lists
qt.insert_many([(10, 20), (30, 40), (50, 60)])

# Using NumPy arrays (requires NumPy)
import numpy as np
points = np.array([[10, 20], [30, 40], [50, 60]])
qt.insert_many_np(points)  # Use insert_many_np for NumPy arrays

Does fastquadtree support multiprocessing? Yes, fastquadtree objects can be serialized to bytes using the to_bytes() method and deserialized back using from_bytes(). This allows you to share quadtree data across processes and even cache prebuilt trees to disk. When using QuadTreeObjects or RectQuadTreeObjects, you must pass include_objects=True to to_bytes() to serialize Python objects, and allow_objects=True to from_bytes() when loading. By default, objects are skipped for safety, as deserializing untrusted Python objects can be unsafe. See the interactive v2 demo for an example of saving and loading a quadtree, and the QuadTreeObjects API docs for full details on the serialization methods.

License

MIT. See LICENSE.

Acknowledgments

• Python libraries compared: PyQtree, e-pyquadtree, Rtree, nontree, quads, Shapely
• Built with PyO3 and maturin

Footnotes

• Uses query_np for Numpy array return values rather than Python lists. ↩

• Uses standard query method returning Python lists. ↩

• Uses Shapely STRtree with Numpy array points and returns. ↩

• Uses QuadTreeObjects with object association. ↩