fastquadtree

Rust-optimized quadtree with a clean Python API

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

Why use fastquadtree

• Clean Python API with no external dependencies and modern typing hints
• The fastest quadtree Python package (>10x faster than pyqtree)
• Prebuilt wheels for Windows, macOS, and Linux
• 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.567x 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.pyqtree import Index  # Drop-in pyqtree shim (6.567x 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: 250,000, Queries: 500
• Fastest total: fastquadtree at 0.030 s

Library	Build (s)	Query (s)	Total (s)	Speed vs PyQtree
fastquadtree	0.023	0.007	0.030	41.31×
Shapely STRtree	0.094	0.049	0.143	8.67×
nontree-QuadTree	0.448	0.475	0.924	1.34×
Rtree	0.801	0.225	1.025	1.21×
e-pyquadtree	0.666	0.451	1.117	1.11×
PyQtree	1.066	0.175	1.241	1.00×
quads	0.969	0.330	1.299	0.96×

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, track_objects=False, start_id=1)

• 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
• track_objects — if True, the wrapper maintains an id → object map for convenience.
• start_id — starting value for auto-assigned ids

Key Methods

• insert(xy, *, id=None, obj=None) -> int

• query(rect, *, as_items=False) -> list

• nearest_neighbor(xy, *, as_item=False) -> (id, x, y) | Item | None

• delete(id, xy) -> bool

There are more methods and object tracking versions in the docs.

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.
• The wrapper maintains an object map only if the quadtree was constructed with track_objects=True. If you don't need it, leave it off for best performance.
• 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, xy) 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 track_objects=True, 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 the NumPy array variant of insert_many for better performance. 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.

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. See the interactive v2 demo for an example of saving and loading a quadtree.

License

MIT. See LICENSE.

Acknowledgments

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