Scikit-Learn · Class

MeanShift

MeanShift performs unsupervised clustering with a flat kernel, automatically discovering cluster centers from sample density. It updates candidate centroids toward local means and removes near-duplicate candidates.

How it works

MeanShift starts kernel candidates from seeds or a binning scheme, repeatedly moves each candidate toward the mean of nearby samples, then removes nearly duplicate candidates. The surviving centroids define the clusters, while labels associate samples with them; the number of clusters is determined by the data rather than supplied directly.

Syntax

class sklearn.cluster.MeanShift(*, bandwidth=None, seeds=None, bin_seeding=False, min_bin_freq=1, cluster_all=True, n_jobs=None, max_iter=300)

Parameters

Name	Type	Description
`bandwidth`	`float, default=None`	Flat-kernel bandwidth; when omitted, it is estimated with estimate_bandwidth.
`seeds`	`array-like of shape (n_samples, n_features), default=None`	Kernel initialization points.
`bin_seeding`	`bool, default=False`	Whether to use discretized, binned points as initial kernel locations.
`min_bin_freq`	`int, default=1`	Minimum number of points required in a bin when generating seed locations.
`cluster_all`	`bool, default=True`	Whether every sample must receive a cluster assignment, including orphan points.
`max_iter`	`int, default=300`	Maximum number of iterations per seed.
`n_jobs`	`int, default=None`	Number of parallel jobs; None means the default job behavior.

Returns

Fitted estimator with cluster_centers_ containing the coordinates of cluster centers and labels_ containing the label of each sample.

Key points

The estimator applies a flat-kernel mean-shift procedure.
Each candidate centroid is repeatedly updated from the samples in its neighborhood.
Post-processing removes nearly duplicate candidates before producing the final centroids.
Binning can reduce the number of initial kernel locations and improve scalability.
bin_seeding=True initializes kernels from discretized grid locations rather than every sample location.
After fitting, labels_ stores the cluster assignment for every input sample.

Common mistakes

Leaving bandwidth unset triggers an estimate; this can affect scalability, so choose it explicitly when you need predictable behavior.
With cluster_all=False, points outside every kernel are treated as orphans instead of being assigned to a cluster.
High-dimensional inputs can make the algorithm expensive because its complexity approaches quadratic in the number of samples.

Example: Cluster points with an explicit bandwidth

from sklearn.cluster import MeanShift

X = [[1, 1], [1, 0], [0, 1], [8, 8], [8, 9], [9, 8]]
model = MeanShift(bandwidth=2).fit(X)

print(model.labels_)
print(model.cluster_centers_)

Fits MeanShift to two separated groups and prints the assigned labels and learned centroids.

When to use it

Density-based exploratory clustering

You have unlabeled vector data whose groups correspond to dense regions and do not want to choose the number of clusters first.

Mode or centroid discovery

You want to reduce many nearby candidate centers to representative locations after mean-shift updates.

Binned initialization for scalability

A large sample set makes one kernel start per observation costly.

Interview questions

QHow does MeanShift form clusters?

MeanShift is an unsupervised, centroid-based clustering algorithm that uses a flat kernel. It updates candidate centroids toward the mean of points in a neighborhood, then filters near-duplicate candidates.

Follow-up: How is the number of clusters selected? It is induced by the surviving candidate centroids after iterative updates and post-processing, rather than specified as a separate cluster-count parameter.

QWhat does bandwidth control?

bandwidth controls the size of the neighborhood used by the flat kernel. If omitted, scikit-learn estimates it with estimate_bandwidth.

Follow-up: What trade-off does bandwidth introduce? A larger neighborhood generally merges broader regions, while a smaller one can preserve finer structure; it also changes the computational workload.

QHow are initial kernels selected?

Seeds initialize the kernels. If seeds are absent, scikit-learn derives them with get_bin_seeds, using bandwidth as the grid size and default values for the other options.

Follow-up: How can initialization improve scalability? Use fewer seeds, for example by increasing min_bin_freq in the bin-seed calculation.

sklearn.cluster.estimate_bandwidth
sklearn.cluster.get_bin_seeds
sklearn.cluster.mean_shift
sklearn.cluster.KMeans
sklearn.cluster.DBSCAN

Source: MeanShift. Checked 2026-10-15.