UMI-tools: counting molecules instead of sequencing reads

The problem UMIs solve in an NGS pipeline

Every sequencing read that comes off a library is not an independent observation. PCR amplification copies a starting molecule, and the more amplification cycles a library went through, the more reads you get for the same original molecule. If you count reads, you count amplification, not biology.

A Unique Molecular Identifier is a short tag attached to each original molecule before amplification. Reads carrying the same UMI are the same molecule, and the UMI-tools project exists to turn a read stream back into a molecule count.

The scope is broader than the name suggests. The repository covers UMIs, Random Molecular Tags, and single cell RNA-Seq cell barcodes, and it describes itself as tools for handling Unique Molecular Identifiers in NGS data sets. The work was published in Genome Research on 18 January 2017 and is open access, and the project credits its authorship to Ian Sudbery in the package metadata.

The intended user is a bioinformatics analyst with fastq files, a reference genome and an aligner already in the pipeline. UMI-tools assumes you have gone as far as alignment, because the deduplication commands group UMIs that share alignment coordinates.

Six commands split across read preparation and counting

The README divides the suite into two halves, and the split maps onto the pipeline.

The `extract` and `whitelist` commands prepare fastq files for alignment. `extract` removes UMI sequences from the reads and appends them to the read name, while leaving any other barcode such as a library barcode on the read, and it can also filter reads by quality or against a whitelist. `whitelist` builds a list of the real cell barcodes, which matters in droplet-based single cell RNA-Seq where the true barcodes are not known ahead of time.

The `group`, `dedup` and `count` commands then work on aligned data. `dedup` collapses each group of PCR duplicates into one read. `group` uses the same grouping methods but keeps the duplicates, which is what you want when you want to interrogate them yourself. `count` groups, deduplicates and produces a matrix of unique molecules per gene, per cell for single cell data, and `count_tab` does the same from a flat file input.

A sixth command, `prepare_for_em`, takes the output of `group` or `dedup` after it has been name sorted or collated and rewrites it for expectation-maximisation tools such as Salmon or RSEM.

One small inconsistency is worth noting: the README announces that there are currently 6 commands and then describes seven, since `prepare_for_em` is introduced separately after the list. Nobody is misled for long, but it is a sign that the command set has grown past the short list in the documentation.

Network-based methods resolve UMIs that differ by a typo

The deduplication commands make use of network-based methods to resolve similar UMIs that share the same alignment coordinates. The project links to a Genome Research publication for background and to a blog post describing the network-based methods in more detail.

The reason a network is needed at all is sequencing error. A UMI read from a sequencing run has a chance of containing a substitution, and a naive string comparison treats the errored copy as a different molecule. Grouping similar UMIs that land on the same genomic coordinates recovers those pairs instead of inflating the molecule count.

Several deduplication schemes are available and the documentation states plainly which one to use: the recommended method is *directional*. The choice matters because each scheme trades accuracy against the number of reads you are willing to call a duplicate, and the project only names directional as the default choice rather than documenting the others in the README. The full documentation at umi-tools.readthedocs.io is where that comparison lives.

There is also a dedicated tutorial document for single cell work, `Single_cell_tutorial.md`, and a `QUICK_START.md` that covers the most common usage pattern, so the intended path for a new user is a quick start rather than reading the command reference front to back.

Installing with pip or conda, and a C extension to compile

Three installation routes are documented. Conda is offered first, through the bioconda channel:

   $ conda install -c bioconda -c conda-forge umi_tools

The pip route is the shorter one:

   $ pip install umi_tools

To work directly from the repository, clone it and install from the checkout:

   $ git clone https://github.com/CGATOxford/UMI-tools.git

followed by

   $ pip install .

Expect a build step rather than a wheel download, because the project compiles a Cython extension. The build system in `pyproject.toml` requires `setuptools>=42`, `setuptools-scm` and `numpy>=1.7`, and the extension module list names `umi_tools._dedup_umi` built from `umi_tools/_dedup_umi.c`. There is a `setuptools-cython/` directory at the top level of the tree, and the version is dynamic, derived by `setuptools-scm` from the git history, which is why the packaging metadata lists no static version.

The runtime dependencies are the usual analysis stack: `numpy>=1.7`, `pandas>=0.12.0`, `pysam>=0.16.0.1`, `future`, `regex`, `scipy`, `matplotlib` and `pybktree`. The README states the dependency set as `python>=3.5` with `numpy`, `pandas`, `scipy`, `cython`, `pysam`, `future`, `regex` and `matplotlib`.

The command itself is `umi_tools`, and the help output is available per subcommand:

   $ umi_tools --help

or, for one command in isolation,

   $ umi_tools [COMMAND] --help

The project points droplet users at alevin instead

The README carries an important update that is easy to skim past. For droplet-based single cell RNA-Seq, covering platforms such as 10X and inDrop, the project now recommends `alevin` rather than UMI-tools itself.

The difference in approach is specific. Alevin is described as an accurate and convenient end-to-end tool that goes from fastq to a count matrix, and it extends the UMI error correction that lives in UMI-tools while adding the ability to quantify droplet single cell data without discarding multi-mapped reads. That last point is the substantive one: UMI-tools groups by alignment coordinates, and a read that maps to several places is a problem for that model, whereas the Alevin framework is built to keep such reads and quantify them.

So the choice is not a judgement about quality. It is about where in the pipeline the work happens. If you want one tool to take a droplet fastq all the way to a matrix, with error correction folded in, the project points you elsewhere. If you have a UMI workflow already in place, or you are working with bulk data, UMI-tools is the tool described here.

The Alevin documentation and a pre-print are linked from the README, so the recommendation comes with somewhere to go next rather than a dead end.

Maintenance state, licence and what the packaging tells you

The project is MIT licensed, and the repository carries a `LICENSE` file at the top level. The licence is permissive, but it does require keeping the copyright notice, so a lab using the tool in a pipeline, including a commercial one, needs to retain that attribution. This is a description of the licence terms and not legal advice.

The version history is where the detail is. The most recent tagged release is v1.1.6 dated 2024-10-03, preceded by 1.1.5 on 2024-02-14 and 1.1.4 on 2023-03-02. The last push to the default branch was on 2026-10-04, so commits are still landing on master even though the tags are older. Whether that means a release is imminent is not something the documentation says, so plan around the tagged version and read the changelog in the repository before upgrading.

The packaging metadata is candid about maturity. The project classifiers say `Development Status:: 3 - Alpha`, and the `Intended Audience` entries are Science/Research and Developers, with POSIX, Unix and MacOS listed as the operating systems. Alpha is a fair description for a tool that compiles a Cython extension, resolves ambiguous UMIs with a network method, and quietly recommends a different tool for its most fashionable use case.

The repository also carries `step1_unit_test.py` and a `tests/` directory, and the documentation is built with readthedocs from a `.readthedocs.yml` file, so the docs are versioned alongside the code rather than being a stale website.

Editorial conclusion

UMI-tools fits bulk RNA-Seq and targeted pipelines where you already have UMIs in the read and want per-molecule counts without writing a deduplicator yourself, and the install paths through pip or conda are short enough to try in an afternoon. It is the wrong choice for droplet-based single cell work, because the project recommends alevin there, which goes from fastq to a count matrix and keeps multi-mapped reads that UMI-tools would discard. Before adopting it, check three things: the `directional` method against the other deduplication schemes on your own library, since the project calls it the recommended one, the size of your UMI against the error correction settings, and the fact that the newest tagged release is v1.1.6 from 2024-10-03 even though the last push to the branch was on 2026-10-04.

Frequently asked questions

Official sources

1. CGATOxford/UMI-tools on GitHub
2. Issues
3. License: MIT
4. README
5. Releases