hdbscan: HDBSCAN clustering for Python, and what its API actually commits you to

The problem hdbscan solves: clustering when you cannot pick epsilon

DBSCAN needs an epsilon radius. Pick it too small and every point becomes noise; pick it too large and separate clusters merge. There is no principled way to pick it without already knowing the density structure of your data, which is the thing you were trying to discover. HDBSCAN sidesteps this by running DBSCAN conceptually over varying epsilon values and integrating the results, selecting the clustering that gives the best stability over the epsilon range. The README states this directly: it "Performs DBSCAN over varying epsilon values and integrates the result to find a clustering that gives the best stability over epsilon." The practical consequence is that the primary parameter becomes minimum cluster size, which the README calls "intuitive and easy to select." If you have ever spent an afternoon sweeping eps values and eyeballing silhouette scores, that is the problem this package removes. The audience is anyone doing exploratory data analysis on numeric data where the number of groups is unknown: customer segmentation, sensor readings, embedding coordinates, anomaly triage. It is less obviously for people who already know their k and just want k-means to run faster.

How the algorithm produces clusters: hierarchy, stability, and the condensed tree

The mechanism is a two-stage construction. First, the package builds a mutual reachability distance graph and from it a minimum spanning tree, which is exposed after fitting as the reachability distance minimal spanning tree attribute. Second, that tree is converted into a hierarchy of connected components as the distance threshold rises, and each candidate cluster is scored by persistence: how long it survives across the range of distance scales present in the data. The clusterer keeps the clusters that are stable and discards the rest. The README describes two hierarchies available on the fitted object: the condensed cluster hierarchy and the robust single linkage cluster hierarchy, both with methods for plotting and for conversion to Pandas or NetworkX. That conversion matters more than it sounds. It means you can pull the hierarchy into a dataframe and inspect which splits survived, rather than treating the label vector as the only output. Because the hierarchy is computed once, the package supports caching with joblib, and the README claims that re-clustering with different parameters can be "almost free." That claim is about the cached hierarchy, not about the initial fit, which still depends on the size and dimensionality of your input.

The API surface: fit_predict, minimum cluster size, and distance matrices

The package inherits from sklearn classes and the README says it "drops in neatly next to other sklearn clusterers with an identical calling API." The documented example is short: import hdbscan and make_blobs, generate data with make_blobs(1000), construct hdbscan.HDBSCAN(min_cluster_size=10), and call fit_predict(data). Input can be an array, a pandas dataframe, or a sparse matrix of shape (num_samples x num_features). It can also be a precomputed distance matrix, dense or sparse, which is the escape hatch when your data is not Euclidean or when you have already computed pairwise distances for another reason. Beyond labels, the fitted object carries cluster membership strengths, which the README says give "optional soft clustering (and no further compute expense)." Each cluster also receives a persistence score, described as a measure of the relative strength of clusters. That score is the closest thing to a confidence number in the output, and it is worth reading before you trust a label vector. For outlier work, the object exposes outlier_scores_ implementing the GLOSH algorithm, one score per fitted point, with higher values meaning more outlier-like. The README suggests selecting outliers via upper quantiles.

Installation and the API version you are actually installing

The README carries PyPI and conda-forge version badges, so both pip install hdbscan and conda install -c conda-forge hdbscan are the intended routes; the repository does not document a build-from-source path in the material available here. This is where a reader needs to be careful. The README shown here describes the classic API: hdbscan.HDBSCAN(min_cluster_size=10) with fit_predict, and attributes such as outlier_scores_, the condensed tree, and the minimum spanning tree. The current documentation on Read the Docs, which the README links to, documents a newer interface built around hdbscan.HDBSCAN with fit and fit_predict methods and a prediction API, and recent releases in the 0.8.4x line are consistent with that newer line. The README text itself appears to lag the released code. Do not assume the constructor signature, attribute names, or import paths in the README match what pip resolves today. Check the version you installed against the Read the Docs page for that version before writing code against attribute names. This is not a criticism of the algorithm; it is a documentation drift problem that costs an hour if you hit it and nothing if you check first.

Where HDBSCAN is the wrong tool

The failure mode is dimensionality. Density-based clustering depends on a distance metric being meaningful, and in high-dimensional spaces distances concentrate: the nearest and farthest neighbours of a point become comparably far apart. The README makes no claim about high-dimensional performance and its performance notes are explicitly about low-dimensional data, stating that "performance on low dimensional data is better than sklearn's DBSCAN." That qualifier is doing real work. If you are clustering TF-IDF vectors over tens of thousands of vocabulary terms, or raw embeddings of a few hundred dimensions, HDBSCAN will often return either one cluster or all noise, and no amount of minimum cluster size tuning fixes it. Reduce dimensionality first, or use a different method. The second limitation is structural: HDBSCAN labels points as noise. The README frames this as a feature, and for outlier detection it is, but if your downstream pipeline requires every row to carry a cluster id, you now own a second decision about what to do with the noise points. The third is parameter sensitivity in the opposite direction from DBSCAN. Minimum cluster size is easier to reason about than epsilon, but it is not free: set it large and small genuine clusters are absorbed; set it small and the hierarchy fragments. The README calls it "intuitive," which is fair, but intuitive is not the same as insensitive.

Alternatives and the actual difference in approach

The obvious comparison is sklearn's DBSCAN, which the README itself benchmarks against for low-dimensional data. The difference is not speed, it is the parameter. DBSCAN takes eps and min_samples and produces one flat clustering at one density threshold; HDBSCAN takes min_cluster_size and produces a hierarchy it then prunes by stability, so it can recover clusters of differing densities in the same run. If your clusters are all roughly the same density and you already know a sensible eps, DBSCAN is simpler and you gain little from the hierarchy. The second alternative is k-means or Gaussian mixture models. Those require you to specify the number of clusters up front and assume roughly convex, similarly sized groups. HDBSCAN makes neither assumption, which is exactly why it is the better default for exploration and the worse choice when you have a genuine prior on k and want a centroid per cluster. The third is scipy's single linkage, which the README names directly: the package provides a robust single linkage implementation based on Chaudhuri and Dasgupta that it says outperforms scipy's standard single linkage. If you are already using scipy linkage for hierarchical clustering, that is a like-for-like swap worth knowing about, and it is a separate algorithm from HDBSCAN proper.

Licence, maintenance, and what upgrading costs

The package is BSD-3-Clause, which permits commercial and closed-source use provided the copyright notice and licence text are retained and the names of contributors are not used to endorse derived products. That is permissive and unremarkable; the practical obligation is keeping the licence file with your distribution. It is not legal advice and you should have your own counsel review anything that matters. On maintenance, the release cadence visible in the material is active: 0.8.42 in March 2026, 0.8.43 in May 2026, 0.8.44 in June 2026, with the last push to master in June 2026. Frequent patch releases in a 0.8.x line mean the project has not declared a stable 1.0, so pinning a version in your requirements file is worth doing rather than tracking latest. The upgrade cost is dominated by the documentation drift described above: because the README and the current docs describe different API surfaces, a minor version bump can change constructor arguments or attribute names. Before upgrading, read the release notes for the versions between your pinned version and the target, and check the Read the Docs page for the target version rather than the README on master. The BSD licence itself imposes no upgrade obligation, so the cost here is engineering time, not legal exposure.

Editorial conclusion

Adopt hdbscan if you are doing exploratory clustering on low-dimensional numeric data, you do not know the cluster count in advance, and you want noise labelled rather than forced into a cluster. Do not adopt it if your data is high-dimensional sparse text or if you need every point assigned to a cluster, since HDBSCAN will label points as noise. Before relying on it, check which branch you are installing from, because the README describes a different API than the current documentation, and confirm that the minimum cluster size you pick produces a stable hierarchy rather than a single dominant cluster.

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. scikit-learn-contrib/hdbscan on GitHub