---
id: ncls
version: "0.0.70"
license: MIT
license_treatment: permissive
maintenance: aging
---

# ncls — A fast interval tree-like implementation in C, wrapped for the Python ecosystem.

License: permissive · Maintenance: aging · Downloads: 104.3K/mo

## What it is and what it does

NCLS is a Nested Containment List data structure for interval overlap queries, originally from the defunct PyGr library and revived as a standalone tool. It builds on the algorithm described in the original paper and is optimized for speed and memory efficiency compared to traditional interval trees. The package wraps a C implementation with Python bindings and depends only on numpy.

You use NCLS by constructing an index from arrays of interval start and end positions, then query it to find overlaps with new intervals. It supports both single-query (slower, Python-based) and batch-query (faster, C-based) modes. The package is designed for genomic and bioinformatics workflows but works for any interval overlap problem.

Use it for:

- Finding all genomic features that overlap a given region in a genome annotation database.
- Batch-querying multiple query intervals against a large reference set of intervals to identify all pairwise overlaps.
- Building interval indices for read alignment or variant annotation pipelines where speed is critical.
- Detecting overlaps in time-series or coordinate-based data where traditional tree structures are too slow.
- Memory-constrained environments where interval tree memory overhead is prohibitive.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

NCLS provides a fast interval overlap query data structure implemented in C, designed to find which intervals overlap with a given range much faster than traditional interval trees.

Yes, if you need fast interval overlap queries and are comfortable with a compiled dependency. The package is stable, has no known vulnerabilities, and offers significant speed and memory advantages. However, note the deprecation notice recommending an alternative for new projects and the aging maintenance status—evaluate whether that better suits your long-term needs.

## Install

pip install ncls
uv add ncls
poetry add ncls

## Installing ncls

Before you install: Medium install friction due to compiled C extensions; however, pre-built wheels are available for common Python versions and platforms (macOS ARM64, Linux x86_64, i686, musllinux). Last release was recent (2025-07-04), but the package is marked as aging with no commits since then.

License in practice: MIT license is permissive and poses no restrictions on commercial or private use, modification, or redistribution.

Quickstart:

pip install ncls

from ncls import NCLS
import numpy as np

starts = np.array([0, 1, 2])
ends = np.array([100, 101, 102])
ids = np.array([0, 1, 2])

ncls = NCLS(starts, ends, ids)
results = ncls.find_overlap(0, 2)
for interval in results:
    print(interval)

Requires a C compiler and build tools to compile the extension from source if a pre-built wheel is not available for your Python version and platform.

Verify before relying:

- Whether the package's aging maintenance status affects long-term compatibility with future Python versions.
- The deprecation notice recommends ruranges as an alternative; whether NCLS remains the right choice for new projects.
- Minimum Python version requirement, as requires_python is unspecified in the metadata.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: medium
- Maintenance: aging
- Downloads: 104.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

interval overlap queries, interval tree alternative, fast range intersection, genomic interval lookup, nested containment list, interval database, overlap detection, genomics, interval-queries, performance-critical

[View on SkillFed](https://skillfed.io/packages/ncls) · [View on PyPI](https://pypi.org/project/ncls/)