intervaltree

What it is and what it does

intervaltree is a mutable, self-balancing interval tree for Python that stores ranges (intervals) and allows efficient queries by point, by range overlap, or by range envelopment. It was designed to support tagging text and time intervals, where intervals include the lower bound but exclude the upper bound. The package provides a rich API for insertion, deletion, and querying, as well as set-like operations (union, difference, intersection) and restructuring methods (merge, chop, slice).

The tree automatically maintains balance using AVL rebalancing, so you can add and remove intervals without manually managing the structure. It depends only on sortedcontainers for its underlying sorted storage, keeping the dependency footprint minimal. The library supports both Python 2.7 and modern Python versions (3.5 through 3.14), making it suitable for legacy and current codebases alike.

Use it for:

• Tag text spans or time intervals in documents or logs, then query which tags overlap a given point or range.
• Store scheduling or calendar events and find all events that overlap or are contained within a time window.
• Manage genomic or biological sequence annotations where intervals represent features and you need to query overlaps.
• Index spatial or temporal data where you need fast overlap detection between ranges without manual tree balancing.
• Implement interval-based caching or memoization where you store results for ranges and retrieve them by overlap.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A self-balancing interval tree data structure that stores and queries overlapping or enveloped ranges, supporting point lookups, range overlaps, and range envelopment queries.

Yes. intervaltree is a stable, well-maintained library with low install friction, permissive licensing, no known vulnerabilities, and a focused, proven API for a common data structure problem. Install it if you need to store and query overlapping or enveloped ranges; the self-balancing design and rich query interface make it significantly easier than building your own tree.

Install

intervaltree on PyPI

pip install intervaltree

uv add intervaltree

poetry add intervaltree

Installing intervaltree

Before you install

Low install friction with a single pure-Python runtime dependency (sortedcontainers). The package is in production-stable status and has been actively maintained, with the latest release in 2025 and repository last commit in 2025. Supports Python 2.7 and 3.5 through 3.14.

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial use, modification, and distribution with minimal restrictions—suitable for most projects.

Quickstart

pip install intervaltree

from intervaltree import Interval, IntervalTree

t = IntervalTree()
t[1:5] = "data"
result = sorted(t.overlap(2, 4))
print(result)

Verify before relying

• Whether the package's AVL balancing guarantees specific query performance characteristics (e.g., O(log n) lookups) under typical usage patterns.
• Real-world performance comparison with alternative interval tree implementations for large datasets.

Package facts

Evidence: intervaltree-3.2.1-py2.py3-none-any.whl

Keywords: data-structure, interval-tree, intervals, tree

Tags

More Libraries packages