---
id: kmodes
version: "0.12.2"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# kmodes — Python implementations of the k-modes and k-prototypes clustering algorithms for clustering categorical data.

License: permissive · Maintenance: dormant · Downloads: 561.9K/mo

## What it is and what it does

kmodes provides Python implementations of k-modes and k-prototypes clustering, specialized for categorical and mixed data types. Unlike k-means, which clusters numerical data by Euclidean distance, k-modes clusters categorical variables by counting matching categories between points. k-prototypes extends this to handle datasets with both numerical and categorical features. The library mirrors scikit-learn's clustering API, making it familiar to users of that ecosystem.

The package relies on numpy for computation and supports parallel execution via joblib for multiple initialization runs. It includes initialization strategies such as Huang's method and density-based approaches. All runtime dependencies (numpy, scikit-learn, scipy, joblib) are standard data-science libraries with low installation friction.

Use it for:

- Cluster customer records with mixed demographic (categorical) and behavioral (numerical) attributes.
- Segment product categories or survey responses where most features are discrete or nominal.
- Analyze categorical genomic or medical data where Euclidean distance is not meaningful.
- Reduce dimensionality or find patterns in text-encoded or one-hot-encoded feature sets.
- Benchmark or compare k-modes results against k-means on datasets with predominantly categorical features.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Implements k-modes and k-prototypes clustering algorithms for categorical and mixed numerical/categorical data, with a scikit-learn-compatible interface.

Yes, if you need to cluster categorical or mixed-type data and want a scikit-learn-compatible interface. The low install friction and permissive license make it a straightforward choice. However, the dormant maintenance status (last release 2022-09-06) warrants checking compatibility with your current numpy and scikit-learn versions before committing to production use.

## Install

pip install kmodes
uv add kmodes
poetry add kmodes

## Installing kmodes

Before you install: Low friction install with standard dependencies (numpy, scikit-learn, scipy, joblib). Maintenance is dormant—last release was 2022-09-06, though the repository remains active with recent commits and no archived status.

License in practice: MIT license permits commercial and private use with minimal restrictions; you must include the license text in distributions.

Quickstart:

pip install kmodes

import numpy as np
from kmodes.kmodes import KModes

data = np.random.choice(20, (100, 10))
km = KModes(n_clusters=4, init='Huang', n_init=5, verbose=1)
clusters = km.fit_predict(data)

Input data must have consistent data types within columns; NaN values are not accepted and must be handled before clustering.

Verify before relying:

- Whether the dormant maintenance status affects compatibility with current numpy/scikit-learn versions.
- Performance characteristics and scalability limits for large datasets relative to alternatives.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 561.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

categorical clustering, k-modes algorithm, k-prototypes mixed data, categorical data clustering, non-numeric clustering, mode-based clustering, scikit-learn clustering alternative, clustering, categorical-data, scikit-learn-compatible

[View on SkillFed](https://skillfed.io/packages/kmodes) · [View on PyPI](https://pypi.org/project/kmodes/)