hdbscan

library0.8.44pypypi✓ verified 23d ago

hdbscan is a clustering algorithm developed by Campello, Moulavi, and Zimek that extends DBSCAN by converting it into a hierarchical clustering algorithm, then using a technique to extract a flat partitioning from the hierarchy. It handles varying density clusters and can identify noise points. The current version is 0.8.42, with frequent minor releases addressing bugs and adding small features.

data ai-ml

pip install hdbscan

github ↗package ↗

INSTALL

IMPORT

SIG · HDBSCAN

hdbscan

datapythonv0.8.44

Install

9.6s avg

Import

4155ms

Disk

304MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.44 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 9s

py 3.11

✕ build_error

✓ 9.4s

py 3.12

✕ build_error

✓ 9.7s

py 3.13

✕ build_error

✓ 10.4s

py 3.9

✕ build_error

304MB installed

● package 304MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HDBSCAN

✓ from hdbscan import HDBSCAN

✗ import hdbscan; model = hdbscan.HDBSCAN_()

`HDBSCAN_` is an internal alias for the Cython implementation; the public-facing and stable API is `HDBSCAN`.

This quickstart demonstrates how to use `hdbscan.HDBSCAN` to perform clustering on sample data. It initializes the model with key parameters `min_cluster_size` and `min_samples`, then fits the data and retrieves cluster labels. Labels of -1 indicate noise points.

import numpy as np from hdbscan import HDBSCAN from sklearn.datasets import make_blobs # Generate sample data data, _ = make_blobs(n_samples=500, centers=4, cluster_std=0.6, random_state=0) # Initialize HDBSCAN model # min_cluster_size is crucial for defining what constitutes a cluster # min_samples controls how conservative the clustering is, higher values mean more points are declared noise clusterer = HDBSCAN(min_cluster_size=15, min_samples=5, prediction_data=True) # Fit and predict clusters clusterer.fit(data) print(f"Number of clusters found: {len(np.unique(clusterer.labels_)) - (1 if -1 in clusterer.labels_ else 0)}") print(f"First 10 labels: {clusterer.labels_[:10]}") # You can also get probabilities (soft clusters) # print(f"First 10 membership probabilities: {clusterer.probabilities_[:10]}")

Debug

Known issues

breakingHDBSCAN versions prior to 0.8.38 (specifically 0.8.37) had known incompatibilities with NumPy 2.x, leading to build failures. Upgrading to NumPy 2.x requires hdbscan 0.8.38 or newer.

fix

Upgrade hdbscan to version 0.8.38 or later using `pip install --upgrade hdbscan`.

affects: <0.8.38

deprecatedPython 3.7 support was officially deprecated and dropped starting from version 0.8.38.post2. Users on Python 3.7 will not receive new updates or fixes for hdbscan.

fix

Upgrade to Python 3.8 or a newer supported version (e.g., Python 3.10, 3.11, 3.12).

affects: >=0.8.38.post2

gotchaThe `min_cluster_size` and `min_samples` parameters are critical and highly sensitive to the dataset. Incorrect values can lead to over-clustering, under-clustering, or too many noise points. `min_cluster_size` defines the smallest group to be considered a cluster, while `min_samples` (similar to DBSCAN's `minPts`) affects the density threshold for core points. `cluster_selection_epsilon` can also significantly impact results, particularly for merging clusters at different densities.

fix

Experiment with different values, potentially using grid search or visual inspection of clusterings (e.g., using `clusterer.condensed_tree_.plot()` for insight) to find optimal parameters for your specific dataset and problem.

affects: All

gotchaThe internal 'branch detection' algorithm, which significantly improves handling of long, flaring clusters, was introduced in version 0.8.38. This change fundamentally alters how the algorithm processes the hierarchy and may produce different clustering results compared to previous versions, even with identical parameters.

fix

Be aware that results from versions 0.8.38 and later may not be directly comparable to those from earlier versions due to this algorithmic enhancement. Re-evaluate models if upgrading.

affects: <0.8.38

gotchaCalculations for outlier scores (`hdbscan.outlier_scores_`) were fixed in version 0.8.42. Users relying on these scores in earlier versions might have received incorrect or unreliable values.

fix

Upgrade to hdbscan 0.8.42 or later if you depend on accurate outlier scores.

affects: <0.8.42

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hdbscan'

The `hdbscan` package is either not installed in the current Python environment or the environment where it was installed is not active. This can also happen if there's a file named `hdbscan.py` in your working directory causing a name collision.

fix

Ensure `hdbscan` is installed using `pip install hdbscan` or `conda install -c conda-forge hdbscan`. If installed, check your Python environment or rename any local `hdbscan.py` file.

ERROR: Failed building wheel for hdbscan

This error typically occurs during installation, especially on Windows, due to missing C/C++ build tools (like Microsoft Visual C++ 14.0 or greater), or other necessary system dependencies like `Cython`, `numpy`, `scipy`, or `scikit-learn` not being correctly set up for compilation.

fix

For Windows, install 'Microsoft C++ Build Tools' from Visual Studio. Ensure `Cython`, `numpy`, `scipy`, and `scikit-learn` are pre-installed and up-to-date (`pip install cython numpy scipy scikit-learn`). Consider using `conda install -c conda-forge hdbscan` for a more reliable installation, especially if using Anaconda. For Linux, install `build-essential` or `gcc`.

ValueError: Min cluster size must be greater than one

The `min_cluster_size` parameter in `hdbscan.HDBSCAN` is set to 1, but the algorithm requires a minimum cluster size of at least 2 to function correctly and identify distinct clusters.

fix

Set `min_cluster_size` to an integer value greater than 1, for example, `hdbscan.HDBSCAN(min_cluster_size=2)`.

AttributeError: 'HDBSCAN' object has no attribute 'approximate_predict'

This error occurs when attempting to use the `approximate_predict` method directly on an `HDBSCAN` model object without either importing the `approximate_predict` function from `hdbscan.prediction` or ensuring the model was fit with `prediction_data=True`.

fix

To use `approximate_predict`, import it directly: `from hdbscan.prediction import approximate_predict` and call it with the fitted clusterer and new data: `labels, probabilities = approximate_predict(clusterer, new_data)`. Alternatively, ensure `prediction_data=True` was set during model initialization if you intend to access prediction-related attributes directly on the model (though `approximate_predict` is a separate function).

AttributeError: 'HDBSCAN' object has no attribute 'labels_'

The `.labels_` attribute is accessed before the HDBSCAN model has been fitted to data using either the `fit()` or `fit_predict()` method.

fix

Ensure `clusterer.fit(data)` or `clusterer.fit_predict(data)` has been called before attempting to access `clusterer.labels_`.

Upgrade

Version history

0.8.44latest on PyPI · released Jun 1, 2026

Audit

Dependencies

numpyrequiredCore numerical operations and data structures.

scipyrequiredScientific computing functionalities, particularly for sparse matrices and spatial structures.

scikit-learnrequiredProvides base classes, utilities, and potentially some distance metrics. hdbscan aims to be scikit-learn compatible.

Agent activity

19 hits · last 30 days

node

Resources

githubhttp://github.com/scikit-learn-contrib/hdbscan ↗

packagehttps://pypi.org/project/hdbscan/ ↗