---
id: hdbscan
version: "0.8.44"
license: BSD
license_treatment: permissive
maintenance: active
---

# hdbscan — Clustering based on density with variable density clusters

License: permissive · Maintenance: active · Downloads: 3.0M/mo

## 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 above — 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

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

- License: BSD (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 3.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

density-based clustering algorithm, hierarchical clustering with variable density, automatic parameter-free clustering, outlier detection clustering, DBSCAN alternative, exploratory data analysis clustering, robust single linkage clustering, clustering, density-based, outlier-detection

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