umap-learn

library0.5.12pypypi✓ verified 25d ago

UMAP (Uniform Manifold Approximation and Projection) is a general-purpose manifold learning and dimensionality reduction algorithm. It constructs a high-dimensional graph and then searches for a low-dimensional projection of the data that has the closest possible equivalent fuzzy topological structure. The current version is 0.5.12, with a release cadence that includes frequent patch releases and minor updates.

ai-ml data

pip install umap-learn

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UMAP-LEARN

umap-learn

ai-mlpythonv0.5.12

Install

13.7s avg

Import

35654ms

Disk

478MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.12 · 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

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 13.7s · import 35.654s · 472MB

478MB installed

● package 478MB

Code

Verified usage

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

UMAP

✓ import umap reducer = umap.UMAP()

✗ from umap_learn import UMAP

The primary class `UMAP` is typically imported from the top-level `umap` module, not `umap_learn`.

UMAP

✓ from umap import UMAP

Direct import from `umap` module.

This quickstart demonstrates how to use `umap-learn` to reduce the dimensionality of a synthetic dataset. It covers generating data, initializing the `UMAP` reducer with common parameters, and performing the fit and transform operation.

import umap from sklearn.datasets import make_blobs # 1. Generate some sample data X, y = make_blobs(n_samples=500, centers=4, cluster_std=1.0, random_state=42) # 2. Initialize UMAP reducer # n_neighbors: Balances local vs. global structure. Larger values preserve more global structure. # min_dist: Controls how tightly points are packed together. Smaller values lead to denser clusters. # n_components: Desired dimensionality of the output embedding. # random_state: For reproducible results. reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42) # 3. Fit and transform the data embedding = reducer.fit_transform(X) # The 'embedding' now contains the 2D projection of the original data print(f"Original data shape: {X.shape}") print(f"UMAP embedding shape: {embedding.shape}") # print(embedding[:5]) # Display first 5 embedded points

Debug

Known issues

gotchaUMAP is stochastic, and results are not reproducible without setting `random_state`. This applies to both `UMAP` initialization and any subsequent operations like `transform`.

fix

Always pass an integer value to the `random_state` parameter during `UMAP` object initialization, e.g., `umap.UMAP(random_state=42)`.

affects: All versions

gotchaThe `n_neighbors` and `min_dist` parameters heavily influence the resulting manifold structure. Choosing appropriate values is critical for meaningful results, and defaults may not always be optimal for specific datasets.

fix

Experiment with different values for `n_neighbors` (e.g., 5 to 50) and `min_dist` (e.g., 0.0 to 0.5). Higher `n_neighbors` captures more global structure, while lower `min_dist` allows for tighter clustering.

affects: All versions

gotchaThe `transform` method for new, out-of-sample data points performs an *approximate* projection. It is not guaranteed to perfectly preserve the relationships from the training data or match the quality of the `fit_transform` method.

fix

Understand that `transform` is an approximation. If exact embeddings for new data are critical, consider retraining UMAP on the combined dataset or evaluating the stability of the transformation for your application. For small changes to the dataset, `update` might be an option.

affects: All versions

gotchaUMAP's performance relies heavily on `numba` for just-in-time compilation. Issues with `numba` installation or environment configuration (e.g., older compilers) can lead to significant performance degradation or errors.

fix

Ensure `numba` is correctly installed and compatible with your Python environment. Check for any `numba` warnings upon import or during execution. Refer to the `numba` documentation for troubleshooting installation issues.

affects: All versions

gotchaUMAP is not inherently scale-invariant. Features with larger scales will have a disproportionately larger influence on the distance calculations and the resulting manifold structure.

fix

It is generally recommended to preprocess data by scaling or normalizing features before applying UMAP, e.g., using `sklearn.preprocessing.StandardScaler` or `MinMaxScaler`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'umap'

The umap-learn library is not installed in the current Python environment or the environment is not activated.

fix

Install the library using pip: `pip install umap-learn`

ValueError: n_neighbors must be less than the number of data points

The `n_neighbors` parameter is set to a value greater than or equal to the total number of samples in the input data, which is not valid for constructing the neighborhood graph.

fix

Reduce the value of `n_neighbors` to be strictly less than the number of samples in your dataset (e.g., `n_neighbors=min(your_value, X.shape[0] - 1)`).

ValueError: Unknown metric 'cosine'

Certain UMAP metrics (like 'cosine', 'correlation') require the optional `pynndescent` dependency, which is not installed.

fix

Install `umap-learn` with its accelerate extras: `pip install umap-learn[accelerate]` or specifically install `pynndescent`: `pip install pynndescent`

ValueError: Cannot use a precomputed metric together with a metric other than 'precomputed'

When `metric='precomputed'` is specified, the input data `X` is expected to be a square distance matrix, and no other explicit `metric` parameter should be provided, as it conflicts.

fix

Ensure that if `metric='precomputed'`, `X` is a precomputed distance matrix and no other `metric` argument is passed, or ensure the metric is set to 'precomputed' when using a precomputed matrix.

Upgrade

Version history

0.5.12latest on PyPI · released Apr 8, 2026

Audit

Dependencies

numpyrequiredNumerical operations, array handling.

scipyrequiredScientific computing, sparse matrices, spatial algorithms.

scikit-learnrequiredMachine learning utilities, data preprocessing, dataset generation.

numbarequiredJust-in-time compiler for performance-critical code sections.

pynndescentrequiredApproximate nearest neighbor search algorithm, used by UMAP.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/lmcinnes/umap ↗

packagehttps://pypi.org/project/umap-learn/ ↗

homepagehttps://umap-learn.readthedocs.io ↗