---
name: polars-umap
description: >
  UMAP dimensionality reduction as a Polars plugin, powered by Apple's embedding-atlas Rust implementation. Use when writing Python code that uses the polars_umap package.
license: MIT
compatibility: Requires Python >=3.9.
---

# polars-umap

UMAP dimensionality reduction as a Polars plugin, powered by Apple's embedding-atlas Rust implementation

## Installation

```bash
pip install polars-umap
```

## When to use what

| Need | Use |
|------|-----|
| Embed an Array/List embedding column | `pl.col("emb").umap.fit_transform()` |
| Embed several numeric columns | `polars_umap.umap("a", "b", "c")` |
| Add umap_0, umap_1 columns to a frame | `df.umap.fit_transform("emb")` |
| One embedding per group | `pl.col("emb").umap.fit_transform().over("group")` |
| Approximate nearest neighbors | `pl.col("emb").umap.knn(k=15)` |
| UMAP on a precomputed kNN graph | `polars_umap.umap_from_knn("indices", "distances")` |

## API overview

### Functions

Build expressions that run UMAP or nearest neighbor search. They take column names, expressions or selectors.

- `umap`
- `knn`
- `umap_from_knn`

### Namespaces

Importing `polars_umap` registers a `umap` namespace on `pl.Expr`, `pl.DataFrame` and `pl.LazyFrame`.

- `UmapExprNamespace`
- `UmapDataFrameNamespace`
- `UmapLazyFrameNamespace`

## Gotchas

1. Import `polars_umap` before using the `.umap` namespace; the import registers it.
2. UMAP fits on all rows the expression sees. Use `.over(...)` for one fit per group.
3. There is no `transform()` for new points; refit on the combined data instead.
4. Rows with null, NaN or infinite values raise unless `null_policy="ignore"`.

## Best practices

- Pass `random_state` for reproducible embeddings; the default 0.6 layout is then bit-identical across runs and thread counts.
- Use `metric="cosine"` for text embeddings.
- Keep `gpu=False` unless the data is large (around a million rows) or you use `layout="0.5"`.

## Resources

- [Full documentation](https://polars-umap.jeroenjanssens.com/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/jeroenjanssens/polars-umap)
