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.
- 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, thenscaled = 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. - Import the library and create the reducer.
import umap, thenreducer = umap.UMAP(). With no arguments, UMAP uses its defaults and reduces to two dimensions. - 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). - Plot the embedding. With matplotlib,
plt.scatter(embedding[:, 0], embedding[:, 1], c=colours), wherecoloursencodes 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. - Optional: fit once and transform later.
reducer.fit(X)followed byreducer.transform(X)returns the same coordinates asreducer.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 withtransform.
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_neighborsis 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. Thedisconnection_distanceparameter 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
- umap-learn documentation, home and installation
- umap-learn documentation, basic usage
- umap-learn documentation, basic UMAP parameters
- umap-learn documentation, frequently asked questions
- umap-learn documentation, reproducibility
- McInnes, Healy and Melville, UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction, arXiv:1802.03426
- umap-learn source repository, GitHub
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.
| Parameter | Default | Effect described in the documentation | Documentation page |
|---|---|---|---|
| n_neighbors | 15 | Low values focus on local structure; larger values use larger neighbourhoods and capture more global structure | https://umap-learn.readthedocs.io/en/latest/parameters.html |
| min_dist | 0.1 | Low values give clumpier embeddings; larger values prevent UMAP packing points together tightly | https://umap-learn.readthedocs.io/en/latest/parameters.html |
| n_components | 2 | Output dimension; scales well unlike t-SNE, so 10 or 50 can be chosen for clustering | https://umap-learn.readthedocs.io/en/latest/parameters.html |
| metric | euclidean (used in the documentation's examples) | Controls how distance is computed in the input space | https://umap-learn.readthedocs.io/en/latest/parameters.html |
| random_state | None (not set unless provided) | Fixes the seed; with compatibility_layout=True it forces single-threaded layout | https://umap-learn.readthedocs.io/en/latest/reproducibility.html |
| low_memory | False unless set | True uses a slower but less memory-intensive nearest-neighbour search | https://umap-learn.readthedocs.io/en/latest/faq.html |
Sources
- umap-learn documentation: basic UMAP parameters (accessed 2026-11-17)
- umap-learn documentation: reproducibility (accessed 2026-11-17)
- umap-learn documentation: FAQ (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







