Skip to main content
v2026.11,986 entries · CC-BY 4.0

umap-learn: Install, Run and Read UMAP in Python

How to install umap-learn, run UMAP on a scaled data table, read the plot, make it reproducible and fix common errors, from the official documentation.

Written and maintained by CASRAI Editorial Board

Published

On this page

umap-learn is the Python package that implements UMAP (Uniform Manifold Approximation and Projection), a dimension reduction algorithm that turns a table of many measured variables per sample into a small number of coordinates, two by default, that you can plot and cluster. You install it with pip install umap-learn (the import name is umap), create a umap.UMAP() object, and call fit_transform on a scaled data matrix.

This page follows the project’s own documentation: installation, a first run on your own table, the parameters that change the result, how to read the plot, how to make a run repeatable, and what to check when something goes wrong. Facts about the package come from the official documentation at umap-learn.readthedocs.io.

What umap-learn is used for in research

Researchers use umap-learn to look at structure in data that has too many columns to inspect directly: gene or protein expression matrices, spectra, image-derived features, survey item sets or text embeddings. The documentation’s FAQ lists single-cell biology among the typical use cases, and the method itself is described in McInnes and Healy’s paper UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction (arXiv:1802.03426), which is the reference the project asks users to cite. The source code is at github.com/lmcinnes/umap.

There are two common jobs. The first is visualisation: reduce to two components and plot, to see whether samples group by condition, batch, cell type or instrument. The second is a preprocessing step for clustering: the documentation notes that, unlike t-SNE, UMAP scales well with the embedding dimension, so for clustering you can choose a larger target such as 10 or 50 rather than 2. If you are deciding between UMAP and t-SNE for a specific purpose, the CASRAI comparison UMAP vs t-SNE sets the two methods side by side.

How to install umap-learn

The documentation gives two installation routes, both using the package name umap-learn:

  • PyPI: pip install umap-learn
  • conda-forge: conda install -c conda-forge umap-learn

The PyPI route assumes that numba and scikit-learn (and through it numpy and scipy) are available, and the install pulls them in as dependencies. Two installation traps appear in the project FAQ. First, the package called umap on PyPI is a different project: installing it at any point, instead of umap-learn, can cause serious problems, and the FAQ’s remedy is to remove everything UMAP-related from your site-packages directory and reinstall umap-learn. Second, UMAP does not support 32-bit Windows because of Numba issues on that platform. For a clean, recorded environment, see the CASRAI guide on sharing a reproducible conda environment.

How to run UMAP on your data step by step

The documentation’s basic-usage page walks through a table of penguin measurements whose columns are on different scales. The same sequence applies to any numeric table, shown here with a pandas DataFrame df and a list of numeric column names features.

  1. Select numeric features and scale them. Features measured in different units dominate the distance calculation unless they are standardised, so the documentation scales first: from sklearn.preprocessing import StandardScaler, then scaled = StandardScaler().fit_transform(df[features]). The FAQ adds the exception: do not normalise each feature independently when the features have meaningful relationships to one another, such as latitude and longitude.
  2. Import the library and create the reducer. import umap, then reducer = umap.UMAP(). With no arguments, UMAP uses its defaults and reduces to two dimensions.
  3. Fit and transform. embedding = reducer.fit_transform(scaled). The result is an array with one row per sample and two columns; for the 333-row penguin table in the documentation, the shape is (333, 2).
  4. Plot the embedding. With matplotlib, plt.scatter(embedding[:, 0], embedding[:, 1], c=colours), where colours encodes a label you already know, such as treatment group or species. Colouring by a known label is how you check whether the embedding separates what you expect it to separate.
  5. Optional: fit once and transform later. reducer.fit(X) followed by reducer.transform(X) returns the same coordinates as reducer.embedding_ for the training data (the documentation demonstrates this on the 1,797-sample digits dataset, shape (1797, 2)). The same fitted reducer can also be applied to new samples with transform.

Parameters that change the result

Four parameters account for most of the variation between runs. The data table below lists each with the default and the effect the documentation’s parameters page describes. In practice, change one at a time and compare plots: n_neighbors sets how local the structure is, min_dist sets how tightly points may pack, n_components sets the output dimension, and metric sets how distance is measured in the input space.

How to read the output

The two columns of embedding are coordinates produced by the algorithm. They are not measured variables, have no units, and cannot be read off as “axis 1 is expression level”. What carries information is which points sit near one another and which are separated.

  • Neighbourhoods are the reliable part. UMAP is built to keep each sample close to its nearest neighbours from the original space. A group of samples that stays together across several settings of n_neighbors is more credible than one that appears at only one setting.
  • Do not read density literally. The FAQ states that UMAP does not preserve density well, so a tight blob is not evidence that those samples are more similar than the samples in a looser blob. Cluster sizes and gaps in the picture are likewise a product of the settings, in particular min_dist, which the parameters page says gives clumpier embeddings when low and prevents tight packing when larger.
  • Cluster the embedding with a density-based method. The FAQ calls K-Means a poor choice for UMAP output because UMAP does not produce clean spherical clusters, and recommends HDBSCAN or a similar density-based algorithm. For very high-dimensional data (300 or more columns) it suggests this typical pipeline: PCA to about 50 dimensions, UMAP to 10 to 20, then HDBSCAN. CASRAI’s guide to PCA in Python covers the first step and cluster analysis in Python covers common clustering choices.
  • Check for disconnected points. Samples with no near neighbours can be wrongly pulled into the manifold. UMAP warns if vertices become disconnected; umap.utils.disconnected_vertices() identifies them so that you can filter them out or refit without them. The disconnection_distance parameter cuts any graph edge longer than its value.

Making a run repeatable

UMAP is stochastic, and the reproducibility page of the documentation states that the seed is not set unless you provide one. Whenever the picture goes into a paper, set random_state. There is a cost, summarised in the table below, because multi-threaded updates in the original optimiser race one another in a way a seed cannot control.

Configuration (from the documentation’s examples) Repeatable? Parallel layout?
umap.UMAP(compatibility_layout=True), no seed No Yes, uses Numba parallelism
umap.UMAP(compatibility_layout=True, random_state=42) Yes No: single-threaded layout (n_jobs set to one), slower
umap.UMAP(random_state=42, compatibility_layout=False, optimizer="adam") Yes Yes

Two further points matter for a methods section. Switching optimiser changes the embedding, so an Adam run will not match a compatibility-layout run even with the same seed. And exact reproducibility also depends on the software around UMAP: the documentation lists Numba, NumPy, the BLAS library, SciPy, scikit-learn and PyNNDescent. Record all package versions alongside the seed; the CASRAI dictionary entry on computational reproducibility explains why that is part of the result, not a footnote.

Troubleshooting umap-learn

These are the problems the project FAQ documents, with its recommended fix.

Symptom Cause given in the documentation Fix
Strange errors after installing The umap package was installed instead of, or alongside, umap-learn Remove everything UMAP-related from site-packages, then reinstall umap-learn
import umap fails or loads the wrong thing A file named umap.py in the current directory is loaded in place of the module Rename your file
Out of memory on a dataset that is not especially large Default approximate nearest-neighbour search uses more memory Set low_memory=True (slower, less memory)
UMAP uses every CPU core Without a random seed it uses Numba’s parallel implementation on all available cores Set the NUMBA_NUM_THREADS environment variable
Warning about disconnected vertices Points whose nearest neighbours are maximally far away, for example samples sharing no features under a Jaccard metric Find them with umap.utils.disconnected_vertices(); filter them out or refit; consider disconnection_distance
Different picture on every run No random_state set Set random_state; see the repeatability table above
Install fails on 32-bit Windows Numba issues on that platform Use a 64-bit Python

Free alternatives to umap-learn

Which tool fits depends on your language and hardware. The options below are the ones the project documentation or CASRAI’s own guides cover.

Alternative Language What the sources say
uwot R (CRAN) Recommended in the UMAP FAQ as a pure R implementation of UMAP
umap (R package) R (CRAN) Wraps the Python code through reticulate and also includes a pure R implementation
NVIDIA RAPIDS cuML UMAP Python, GPU The FAQ’s pointer for GPU use of UMAP
t-SNE Python (scikit-learn) A different method with a different dimension-scaling behaviour; see t-SNE in scikit-learn
PCA Python (scikit-learn) A linear method that the FAQ also uses as the first step before UMAP

The FAQ also lists umapr, another reticulate wrapper, with the caveat that it may not be actively developed.

Sources

Data: umap-learn UMAP parameters: documented defaults and effects

The four main UMAP constructor parameters in umap-learn, with the default value and the effect stated on the project's parameters page, compiled from the official umap-learn documentation.

umap-learn UMAP parameters: documented defaults and effects
ParameterDefaultEffect described in the documentationDocumentation page
n_neighbors15Low values focus on local structure; larger values use larger neighbourhoods and capture more global structurehttps://umap-learn.readthedocs.io/en/latest/parameters.html
min_dist0.1Low values give clumpier embeddings; larger values prevent UMAP packing points together tightlyhttps://umap-learn.readthedocs.io/en/latest/parameters.html
n_components2Output dimension; scales well unlike t-SNE, so 10 or 50 can be chosen for clusteringhttps://umap-learn.readthedocs.io/en/latest/parameters.html
metriceuclidean (used in the documentation's examples)Controls how distance is computed in the input spacehttps://umap-learn.readthedocs.io/en/latest/parameters.html
random_stateNone (not set unless provided)Fixes the seed; with compatibility_layout=True it forces single-threaded layouthttps://umap-learn.readthedocs.io/en/latest/reproducibility.html
low_memoryFalse unless setTrue uses a slower but less memory-intensive nearest-neighbour searchhttps://umap-learn.readthedocs.io/en/latest/faq.html

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about umap-learn: Install, Run and Read UMAP in Python

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →