hdbscan: the build needs numpy 2, the runtime allows numpy 1, and three CI systems are still in the tree
A high performance implementation of HDBSCAN clustering.
At a glance
- What is it?
- A Cython implementation of hierarchical density-based clustering with an sklearn-compatible calling API, packaged by a setup.py that cythonizes six extensions while the project metadata lives in pyproject.toml. Its fastest claims point at version 0.7 notebooks, the licence is spelled three different ways, and the repository still carries Travis, Circle and Azure Pipelines configuration at once.
- Who is it for?
- This is the right choice when cluster density varies and you do not want to sweep epsilon, and the sklearn-compatible surface means it drops into an existing pipeline without a wrapper. Two things to know before you install from source.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- scikit-learn-contrib/hdbscan3,161 ★ · +18
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| scikit-learn-contrib/hdbscan | 3.1k | 3.2k |
18 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The algorithm is DBSCAN over varying epsilon, integrated
The definition in the README is one sentence: HDBSCAN performs DBSCAN over varying epsilon values and integrates the result to find a clustering that gives the best stability over epsilon. The name expands to Hierarchical Density-Based Spatial Clustering of Applications with Noise. Two consequences follow from that construction. Clusters of varying densities become findable, which plain DBSCAN cannot do, and parameter selection becomes less of a problem, because the single parameter left is the minimum cluster size, described as intuitive and easy to select. The claim that follows is that it returns a good clustering with little or no tuning. The method is attributed to two papers, one by Campello, Moulavi and Sander in 2013 on density-based clustering based on hierarchical density estimates, and one by McInnes and Healy at ICDMW 2017 on the accelerated version, which is the paper behind the implementation here.
Every speed claim points at a version 0.7 notebook
The performance section is written in the present tense and every piece of evidence behind it is a notebook pinned to an older series. The claims are substantial: orders of magnitude faster than the reference Java implementation, currently faster than highly optimized single linkage implementations in C and C++, and better than scikit-learn's DBSCAN on low dimensional data. Each is backed by a link into the notebooks directory, and two of those notebook filenames carry the version in the name, Benchmarking scalability of clustering implementations-v0.7. The current package version is 0.8.44. So the fastest statements in the documentation describe a release seven minor series behind the one you would install. One performance feature does still hold generally: joblib caching, which the README says makes re-clustering with different parameters almost free.
The build asks for numpy 2 while the runtime allows numpy 1
The dependency story splits in two, and the two halves disagree. The build requirements ask for setuptools, wheel, Cython from 3.0.11 up to but not including 4, and numpy from 2.0 up to but not including 3. The runtime dependencies ask for numpy from 1.20 up to but not including 3, scipy from 1.0, scikit-learn from 1.6 and joblib from 1.0. So a machine held at numpy 1 can run the package perfectly well and cannot compile it. The compiled part is not small: setup.py cythonizes six extensions, the tree, the linkage, the Boruvka components, the reachability code, the prediction utilities and the distance metrics, and it subclasses the build command to append numpy's include directory. There is also both a setup.py and a pyproject.toml, which is a transitional shape worth knowing about before you file anything.
The same four dependencies are declared in three files
Runtime dependencies appear three times and the lists match line for line. The project table in pyproject.toml names numpy, scipy, scikit-learn and joblib with the same bounds as requirements.txt, which repeats them verbatim. A conda environment file sits beside them for the conda-forge route the badges advertise. The packaging configuration declares two packages, hdbscan and hdbscan.tests, so the test module ships inside the wheel, and one package data entry, a .pxd header for the distance metrics. Development status is classified as Beta while the version reads 0.8.44, and the Python floor is 3.10 with classifiers running through 3.14, plus classifiers for both C and Python because of the extension modules.
Travis, Circle and Azure Pipelines all sit in the root
Three continuous integration configurations coexist in a repository whose newest release is 0.8.44. There is a Travis configuration file, a Circle configuration file and an Azure Pipelines configuration file, alongside a ci_scripts directory and a file of Oryx build commands, which is the build service Azure uses for automated machine learning images. The development dependency group agrees with the Azure choice, since its test tooling includes a pytest plugin named for Azure Pipelines alongside coverage and benchmark plugins. And the README still opens with a Travis build status badge, which means the badge readers see and the system that actually runs the tests are not the same one. There is also a .idea directory committed at the root, so someone pushed their IDE project files at some point.
The licence is spelled three different ways
Three records describe the same licence and none of them matches the others exactly. The repository metadata gives BSD-3-Clause. The project table in pyproject.toml gives a bare BSD with no clause number. The classifier list gives the generic OSI Approved marker with no licence named at all. The LICENSE file itself sits at the root, and the licence badge at the top of the README points at it. So the authoritative text is unambiguous, but any automated check that reads the manifest rather than the file will report a less specific grant than the project actually offers. This is a small thing that costs nothing to get right and is the kind of mismatch that trips a compliance pipeline.
Two ReadTheDocs domains, and the homepage is plain http
The documentation is linked from three places and they do not agree. The repository homepage field points at one ReadTheDocs domain over plain http, with an io ending. The badge near the top of the README targets a different ReadTheDocs domain, with an org ending and https. The prose later in the README links the tutorials and documentation to the io domain again, this time with the .io host and a full path. Two of the three are consistent with each other and the third is not, and the field that other tools read first, the homepage, is the one using http. Worth resolving before a link checker or a citation starts disagreeing with the documentation.
The fitted object carries three trees, two scores and a converter
What you get back from a fit is more than labels. Three structures are exposed: the condensed cluster hierarchy, the single linkage hierarchy that survives outliers, and the reachability distance minimal spanning tree. Each comes with plotting methods and a way to convert to Pandas or to NetworkX for further analysis. Two scores ride along as well. Cluster membership strengths give an optional soft clustering with no further compute expense, since the information is already there. And every cluster receives a persistence score expressing its stability across the range of distance scales in the data, which is a relative strength measure rather than an absolute one, so a high score means this cluster held together across scales rather than that it is large. Outlier detection is a separate attribute, outlier_scores_, one value per fitted point from the GLOSH algorithm, with higher meaning more outlier-like and upper quantiles suggested as the selection method. The single linkage algorithm of Chaudhuri and Dasgupta is offered in its own right, implemented faster than the scipy equivalent.
Editorial conclusion
This is the right choice when cluster density varies and you do not want to sweep epsilon, and the sklearn-compatible surface means it drops into an existing pipeline without a wrapper. Two things to know before you install from source. The build requirement asks for numpy 2 while the runtime dependency allows anything from 1.20, so a machine pinned to numpy 1 can run the package but cannot build it. And the performance evidence in the documentation is tied to version 0.7 notebooks while the current version is 0.8.44, so treat the speed claims as historical. For reproducibility, depend on the released version rather than the default branch, and check the three declaration files for dependencies instead of trusting any one of them.
Frequently asked questions
what does hdbscan stand for
Hierarchical Density-Based Spatial Clustering of Applications with Noise. It performs DBSCAN over varying epsilon values and integrates the result to find a clustering that gives the best stability over epsilon.
what is hdbscan clustering
A density-based clustering approach that runs DBSCAN across varying epsilon values and integrates the results, so it can find clusters of varying densities rather than one density at a time. Its primary parameter is the minimum cluster size.
How do I install hdbscan in python?
The README's usage section starts at the import, so no install line appears there. The badges at the top of the file point at the PyPI project and a conda-forge package, and the manifest requires Python 3.10 or newer.
Is HDBSCAN better than DBSCAN?
The repository states the differences rather than settling the comparison. It can find clusters of varying densities, which DBSCAN cannot, and it reduces parameter selection to the minimum cluster size. The speed and quality claims are made in notebooks linked from the README, two of which are named for version 0.7.
Does hdbscan do outlier detection?
Yes, with the GLOSH algorithm. After fitting, the scores are read from the outlier_scores_ attribute as one value per fitted point, higher values meaning more outlier-like, and the README suggests selecting outliers through upper quantiles.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/scikit-learn-contrib-hdbscan)Star history chart for your README
[](https://hysenlabs.com/projects/scikit-learn-contrib-hdbscan)Was this useful?