# fgumi: A Rust rewrite of fgbio's UMI pipeline that is now the recommended default

> Fulcrum Genomics ships fgumi, a Rust suite that mirrors fgbio's UMI tools and claims production parity as of v0.5.0. This review covers what it does, how it differs from fgbio, and where you should still be cautious.

**fulcrumgenomics/fgumi** — High-performance UMI tools for NGS data analysis

- Repository: https://github.com/fulcrumgenomics/fgumi
- Website: https://fgumi.readthedocs.io/en/latest/
- Stars: 61 · Forks: 3
- Language: Rust
- License: MIT
- Published: 2026-08-22 · Updated: 2026-08-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/fulcrumgenomics-fgumi

## What fgumi is and who it targets

fgumi is a suite of command-line tools for processing unique molecular index (UMI) data in next-generation sequencing. It is written in Rust and distributed under the MIT license. The project is maintained by Fulcrum Genomics, the same group behind fgbio, which is the Java-based tool that has been the standard for UMI consensus calling. The stated goal is to provide equivalent functionality with higher performance. The README declares production readiness as of v0.5.0, calling it the fgbio-parity release. The target audience is bioinformaticians who run pipelines that extract UMIs, group reads, call consensus sequences, and deduplicate PCR duplicates. If you already use fgbio, fgumi is a drop-in replacement for most commands, with a few documented differences.

## The core commands and the workflow they replace

The toolset covers the full UMI workflow. The extract command reads FASTQ files and writes an unaligned BAM with UMI tags. The group command groups reads by UMI, and dedup marks or removes PCR duplicates. Consensus calling is split into three commands: simplex for single-strand consensus, duplex for double-strand consensus, and codec for CODEC consensus. There is also filter to quality-filter consensus reads, clip to trim overlapping pairs, and duplex-metrics to collect duplex-specific QC. The README maps each command to its fgbio equivalent. For example, extract corresponds to fgbio ExtractUmisFromBam, and group corresponds to GroupReadsByUmi. This mapping is useful when migrating a pipeline, because you can replace one command at a time rather than rewriting the whole workflow.

## Installation and build options

You can install fgumi in three ways. The simplest is to download a pre-built binary from the GitHub releases page, which the README says is available for the most common operating systems and CPU architectures. If you have Cargo installed, run cargo install fgumi. To build from source, clone the repository and run cargo build --release. There are three optional features: compare, simulate, and profile-adjacency. The compare feature enables commands for comparing BAMs and metrics, which is useful for validating fgumi's output against fgbio. The simulate feature generates synthetic test data. The profile-adjacency feature adds profiling output for the adjacency UMI assigner. These features are not enabled by default, so you must build with --features to use them. For example, cargo build --release --features compare.

## How the UMI extraction and grouping works

The basic workflow starts with fgumi extract. The command takes paired FASTQ files and a read structure that defines where the UMI is located. In the example, the structure +T +M means the first read is template only and the second read has a UMI followed by template. The output is an unaligned BAM with the UMI stored in a tag. This is the same approach fgbio uses, which makes sense because the tools are designed to be compatible. After extraction, the optional correct command can fix UMIs that are close to a known set, which is useful for fixed UMI panels. The group command then assigns reads to UMI families. The README mentions multiple assignment strategies, but the details are not in the supplied material. The zipper command later merges alignments back onto the unmapped BAM, restoring tags, which is a step needed after alignment.

## Known divergences from fgbio and why they matter

The README is explicit that fgumi is not a byte-for-byte clone of fgbio. The two most visible differences are in the MI tag values and in the dedup --no-umi behavior. For dedup without UMI, fgumi drops fgbio's strand-of-origin split, which means it treats reads differently when there is no UMI to distinguish strands. This is a deliberate change to match Picard MarkDuplicates. For the MI tag, the values may differ in format or content, which could affect downstream tools that parse the tag directly. The README says these divergences are catalogued in the migration guide. If you use fgbio in a regulated or validated pipeline, you need to check that your variant callers and QC scripts do not depend on the exact MI format. The README also asks users to open an issue for any divergence that is not documented, which is a sign that the list is not assumed to be complete.

## Performance and the reason to switch from fgbio

The project's main selling point is performance. The README calls the tools high-performance and recommends fgumi over fgbio for UMI processing. The performance tuning guide is linked, covering threading, memory, and compression optimization. The Rust implementation should give a speed advantage over fgbio's JVM-based approach, especially for large BAMs. However, the README does not provide any benchmark numbers. You cannot confirm the actual speedup from the supplied material. If you are considering a switch, you should run your own benchmarks with the compare feature to measure both speed and output equivalence. The performance tuning guide is the place to start, but the README does not summarize its contents.

## A real alternative: fgbio and the migration path

The obvious alternative is fgbio itself, which is the Java tool that fgumi is designed to replace. The two tools share the same command structure, so migrating is mostly a matter of changing command names. The migration guide maps each fgumi command to its fgbio equivalent. The key difference is the language and runtime: fgbio runs on the JVM, while fgumi is a native Rust binary. That affects startup time, memory footprint, and raw throughput. The README also mentions other tools like gatk UmiAwareMarkDuplicatesWithMateCigar and umi-tools dedup as equivalents for the dedup command. Those are separate projects with their own algorithms. If you are not tied to fgbio, you could use those instead, but fgumi's advantage is that it covers the whole workflow in one tool.

## Maintenance, licensing, and what to verify first

The project is actively maintained, with the latest release v0.7.0 pushed on 2026-08-25, and releases coming out roughly monthly. The repository is not archived. The license is MIT, which is permissive and allows commercial use without restrictions beyond attribution. That is a low-risk license for most organizations. The README includes a Zenodo DOI, which suggests the project is citable for academic use. Before adopting fgumi, you should verify that the documented divergences do not affect your data. The best way is to run the compare feature on a representative BAM and compare the metrics and BAM output to fgbio. The README also advises validating against your own data before switching. That is not generic advice; it is specific to this tool because the divergences are intentional and could change your results.

## Conclusion

Adopt fgumi if you run UMI-based NGS pipelines and want a faster, Rust-native alternative to fgbio, especially for large WGS or targeted panels. Do not adopt it if you rely on fgbio's exact MI tag format or the strand-of-origin split in dedup --no-umi, because those differ intentionally. Before switching, run the compare feature on your own BAMs and metrics, and read the migration guide to confirm the documented divergences do not affect your variant calls.

## FAQ

### Can I use fgumi instead of fgbio for UMI processing?

Yes. Output is validated against fgbio across a wide range of data from sequencing vendors, and fgumi is recommended over fgbio for UMI processing as of the v0.5.0 parity release. Validate against your own data before switching.

### How do I install fgumi?

Three routes: a pre-built binary attached to each release, cargo install fgumi for the published crate, or clone the repository and run cargo build --release. Only the source route lets you enable optional features.

### Which consensus callers does fgumi provide?

Three: simplex for single-strand consensus, duplex for double-strand consensus, and codec for CODEC consensus, alongside a filter command for quality filtering of consensus reads.

### What Rust version does fgumi need to build from source?

The package uses edition 2024 and declares a minimum Rust version of 1.93.0. A toolchain file at the repository root pins the exact version used for development.

## Sources

- [Official documentation](https://fgumi.readthedocs.io/en/latest/)
- [Official README](https://github.com/fulcrumgenomics/fgumi#readme)
- [Project repository](https://github.com/fulcrumgenomics/fgumi)
- [Release notes](https://github.com/fulcrumgenomics/fgumi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fulcrumgenomics-fgumi