hdbscan

What it is and what it does

HDBSCAN is a clustering algorithm that extends DBSCAN by performing density-based clustering over varying epsilon values and integrating results to find stable clusters. Unlike DBSCAN, it handles clusters of different densities and is robust to parameter selection—the main tunable parameter, minimum cluster size, is intuitive to set. The package accepts arrays, dataframes, or sparse matrices of shape (num_samples x num_features), or distance matrices between samples, and depends on numpy, scipy, scikit-learn, and joblib.

Beyond basic clustering, HDBSCAN provides outlier detection via the GLOSH algorithm, visualization tools for cluster hierarchies and reachability distances, soft clustering with membership strengths, and cluster persistence scores indicating stability. It also includes a RobustSingleLinkage implementation and a BranchDetector for detecting branching structures in clusters. The implementation prioritizes performance.

Use it for:

• Exploratory data analysis on unlabeled datasets where cluster count and density are unknown.
• Outlier detection by accessing outlier_scores_ after fitting to identify anomalous points.
• Clustering with automatic parameter selection when you want to avoid extensive tuning.
• Soft clustering assignments to understand cluster membership confidence for each point.
• Detecting branching or hierarchical structures in cluster data using BranchDetector.

Worth the install?

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

HDBSCAN performs hierarchical density-based clustering that automatically finds clusters of varying densities with minimal parameter tuning, and includes outlier detection and branch-detection capabilities.

Yes. HDBSCAN is actively maintained, has no known vulnerabilities, works with current Python versions (3.10–3.14), and solves a real problem—automatic, parameter-light density-based clustering with variable cluster sizes. The medium install friction is manageable given prebuilt wheels. It is well-suited for exploratory clustering and outlier detection.

Install

hdbscan on PyPI

pip install hdbscan

uv add hdbscan

poetry add hdbscan

Installing hdbscan

Before you install

Medium install friction due to compiled C components, but prebuilt wheels are available for Python 3.10, 3.11, 3.12, 3.13, and 3.14 on macOS, Linux, and Windows. Maintenance is active with a recent release 74 days ago.

License in practice

BSD license is permissive, allowing use in commercial and proprietary projects with minimal restrictions beyond attribution.

Quickstart

pip install hdbscan

import hdbscan
from sklearn.datasets import make_blobs

data, _ = make_blobs(1000)
clusterer = hdbscan.HDBSCAN(min_cluster_size=10)
cluster_labels = clusterer.fit_predict(data)

Requires Python 3.10 or later; compiled C extension requires a compatible build environment or prebuilt wheel for your platform.

Verify before relying

• Whether the package's soft clustering and cluster persistence scoring are suitable for your specific use case.
• Performance characteristics on your dataset size and dimensionality compared to alternatives.
• Compatibility with sparse matrix inputs beyond what the description explicitly confirms.

Package facts

Evidence: hdbscan-0.8.44-cp310-cp310-macosx_10_9_universal2.whl; hdbscan-0.8.44-cp310-cp310-macosx_15_0_x86_64.whl; hdbscan-0.8.44-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; hdbscan-0.8.44-cp310-cp310-win_amd64.whl; hdbscan-0.8.44-cp311-cp311-macosx_10_9_universal2.whl; hdbscan-0.8.44-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; hdbscan-0.8.44-cp311-cp311-win_amd64.whl; hdbscan-0.8.44-cp312-cp312-macosx_10_13_universal2.whl; hdbscan-0.8.44-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; hdbscan-0.8.44-cp312-cp312-win_amd64.whl; hdbscan-0.8.44-cp313-cp313-macosx_10_13_universal2.whl; hdbscan-0.8.44-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; hdbscan-0.8.44-cp313-cp313-win_amd64.whl; hdbscan-0.8.44-cp314-cp314-macosx_10_15_universal2.whl; hdbscan-0.8.44-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; hdbscan-0.8.44-cp314-cp314-win_amd64.whl

Keywords: cluster, clustering, density, hierarchical

Tags

More Software Development packages

Further reading