fastcluster

library1.3.0pypypi✓ verified 85d ago

Fast hierarchical clustering routines for R and Python. Provides efficient implementations of hierarchical clustering (e.g., single, complete, average linkage) with memory-saving algorithms. Current version 1.3.0, with an irregular release cadence (last release 2022).

ai-ml data

pip install fastcluster

package ↗homepage ↗

INSTALL

IMPORT

SIG · FASTCLUSTER

fastcluster

ai-mlpythonv1.3.0

Install

3.6s avg

Import

258ms

Disk

85MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.0 · 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

✓ 4s

py 3.11

✕ build_error

✓ 3.5s

py 3.12

✕ build_error

✓ 3.4s

py 3.13

✕ build_error

✓ 3.5s

py 3.9

✕ build_error

85MB installed

● package 85MB

Code

Verified usage

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

fastcluster.linkage

✓ from fastcluster import linkage

✗ import fastcluster; fastcluster.linkage()

Direct import of function is idiomatic

linkage_vector

✓ from fastcluster import linkage_vector

Used for vectorized input

single

✓ from fastcluster import single

Precomputed linkage methods

Basic usage: create random data, compute linkage matrix using average method.

import numpy as np from fastcluster import linkage # Generate random data: 100 points in 3D X = np.random.rand(100, 3) # Perform hierarchical clustering with average linkage Z = linkage(X, method='average') print(Z.shape) # (99, 4)

Debug

Known issues

gotchaThe 'method' argument uses lowercase names (e.g., 'single', 'complete', 'average') — not 'ward' without the 'ward_D2' distinction that scipy uses. fastcluster's 'ward' is equivalent to scipy's 'ward' (i.e., ward's method on Euclidean distances only, not on precomputed distances).

fix

Use method='ward' for Ward linkage. If you need weighted or centroid methods, note they may differ from scipy.

affects: all

gotchaInput to linkage() expects a 2D array of observations (n_samples, n_features) or a condensed distance matrix. If you pass a square distance matrix, fastcluster will interpret it as observations, leading to silent incorrect results.

fix

Use scipy.spatial.distance.squareform to convert square matrix to condensed form before passing to linkage().

affects: all

deprecatedThe 'fastcluster.linkage' function with 'method'='centroid' or 'median' returns results that differ from scipy.cluster.hierarchy in terms of how the distance matrix is updated. These methods are considered deprecated in favor of scipy's implementations.

fix

Use scipy.cluster.hierarchy.linkage with method='centroid' or 'median' if you need exact scipy compatibility.

affects: >=1.2.0

gotchafastcluster does not support precomputed distance matrices with the 'ward' method — it always recomputes Euclidean distances internally. This can cause unexpected memory usage or errors if you pass a distance matrix expecting Ward's method.

fix

If you must use precomputed distances with Ward linkage, use scipy.cluster.hierarchy.linkage with method='ward' after ensuring distances are Euclidean squared.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'fastcluster'

Package not installed in the current Python environment.

fix

Run 'pip install fastcluster' to install the package.

ValueError: The condensed distance matrix must be of length (n*(n-1)//2) for n points, but got ...

Input to linkage() is a square distance matrix, not a condensed one.

fix

Convert square matrix to condensed form: from scipy.spatial.distance import squareform; condensed = squareform(square_matrix).

TypeError: 'numpy.float64' object cannot be interpreted as an integer

Sometimes occurs when using method='centroid' or 'median' with certain data types or versions of numpy.

fix

Ensure input array is contiguous and dtype is float64. Try X = np.ascontiguousarray(X, dtype=np.float64).

Upgrade

Version history

1.3.0latest on PyPI · released May 6, 2025

Audit

Dependencies

numpyrequiredRequired for array operations

scipyoptionalProvides distance functions and linkage consistency

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://danifold.net ↗