# sourmash: sketching genomes so you can compare them without aligning them

> sourmash is a k-mer analysis multitool that computes MinHash sketches of genomic and metagenomic data so sets can be compared by similarity instead of by alignment. The Rust core does the hashing, the Python layer is the library and command-line interface, and the v4 line carries documented CLI incompatibilities with v3.

**sourmash-bio/sourmash** — Quickly search, compare, and analyze genomic and metagenomic data sets.

- Repository: https://github.com/sourmash-bio/sourmash
- Website: http://sourmash.readthedocs.io/en/latest/
- Stars: 557 · Forks: 93
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/sourmash-bio-sourmash

## What k-mer sketching buys you over alignment

sourmash describes itself as a k-mer analysis multitool whose aim is to provide stable programmatic and command-line APIs for a variety of sequence comparisons. The tag line is Quickly search, compare, and analyze genomic and metagenomic data sets.

The mechanism is a MinHash sketch. Instead of storing the sequence or aligning it to a reference, sourmash computes the hashes of every k-mer in the data, then keeps a fixed-size summary of them. Two data sets can then be compared by comparing their summaries, which is orders of magnitude cheaper than an alignment and produces a similarity estimate rather than an exact answer.

Two features are singled out in the README as the special sauce, and the first is FracMinHash sketching, which enables accurate comparisons including ANI between data sets of different sizes. That is the hard case for plain MinHash. A fixed sketch size gives you constant variance regardless of input, which means a small genome and a large metagenome compared with the same sketch parameter give you a much noisier estimate for the small one. FracMinHash scales the sketch with the data, so the estimate is comparably precise for both.

The second is sourmash gather, described as a combinatorial k-mer approach for more accurate metagenomic profiling. Gather finds the reference genomes in a database whose k-mers are all present in the sample, which is a different question from asking which single reference is closest to the sample. For a metagenome containing a mixture, the answer to the second question is a list, and gather is built around that.

The name is a riff off of Mash, which computes MinHash sketches for genomes, combined with the maintainer's love of whiskey. sourmash 1.0 was published on JOSS with a DOI, and the README asks that the paper be cited if you use it.

The primary language is Python, with the core in Rust, and the documentation is hosted at sourmash.readthedocs.io. The licence is BSD 3-Clause, and the maintainers are C. Titus Brown, Luiz C. Irber, Jr and N. Tessa Pierce-Ward.

## The Rust core and the Python shell around it

sourmash is developed in Python and Rust, and the split is not incidental. The README states that the sourmash/ directory contains the Python library and command-line interface code, and that the src/core/ directory contains the Rust library implementing core functionality.

The Rust side is a Cargo workspace with a single member, src/core, and a default-members list pointing at the same place. The build system in pyproject.toml uses maturin, which is the Rust-aware build backend for Python packages, and the build requirements pin maturin to a bounded range and add cffi. The version in pyproject.toml is 4.9.5-dev, and the license field is BSD-3-Clause.

The interface between the two is a C ABI generated at build time. The Makefile has a rule for include/sourmash.h that depends on a list of Rust source files including the ffi modules for hyperloglog, minhash, signature, nodegraph, index, revindex, storage, manifest and errors, and it runs cbindgen with a cbindgen.toml configuration to produce the header, using RUSTC_BOOTSTRAP=1 in the process. The header is then used to build the Python extension, which is why the make clean target removes src/sourmash/_lowlevel.

This architecture has consequences for anyone installing or packaging it. A source install is a Rust build, not a pure Python one, and the README says you need a Rust environment to build it. It also means the tool can be built to WebAssembly and to WASI, since the Makefile has wasm, wasm-test and wasi targets, with the wasm build enabling a niffler/wasm feature.

There is a Python-only path for those who cannot build Rust locally. The Makefile has an offline target that installs the package with pip using --no-index and --find-links and no build isolation, which is the route for air-gapped or pre-seeded environments.

The project also keeps performance tracking infrastructure: an asv.conf.json and a benchmarks/ directory for the airspeed velocity benchmark suite, a tox.ini, a codecov.yml, and a .sonarcloud.properties file.

## Installing with conda or pip, and the Python version floor

The recommended installation is conda-forge, and the README is direct about why.

```bash
conda install -c conda-forge sourmash-minimal
```

That will install the latest stable version of sourmash 4. The minimal variant is the one named in the README and in the conda-forge badges, and it exists because the base requirements are modest.

The fuller documented flow creates a dedicated environment.

```bash
$ conda create -n sourmash_env -c conda-forge sourmash-minimal
$ conda activate sourmash_env
$ sourmash --help
```

The README notes that this installs the latest released version. The Bioconda channel badge is also present in the README, so a Bioconda package exists alongside the conda-forge one.

pip is the alternative.

```bash
pip install sourmash
```

Requirements are spelled out: sourmash runs under Python 3.11 and later on Windows, Mac OS X and Linux, and the base requirements are screed, cffi, numpy, matplotlib and scipy. The README says conda will install everything necessary and is the recommended installation method.

That Python floor is worth noticing because the badges advertise 3.11, 3.12 and 3.13, and the Makefile's test target runs tox with the py311 environment, so 3.11 is the version the project tests against first. Older interpreters are not supported in this generation of the tool.

Debian packaging exists too, with badges for both testing and unstable. A quickstart tutorial is linked from the README for the first run.

There is also a Nix dimension, with flake.nix, flake.lock, shell.nix, default.nix and dev.yml in the tree, plus a pixi.lock, which tells you the project supports a range of reproducible environment managers rather than one.

## The three-command workflow from the README

The README opens with a usage block that is worth reading as the intended shape of a session, because the three commands are a sketch, a compare and a plot.

```bash
sourmash sketch dna *.fq.gz
sourmash compare *.sig -o distances.cmp -k 31
sourmash plot distances.cmp
```

Step one turns raw reads into signatures. Step two compares the signatures pairwise and writes a distance matrix to a file, with -k 31 setting the k-mer size and -o naming the output. Step three renders the matrix.

The separation is the point. Sketching is the expensive step and it happens once per data set; the signature files are small and portable, so a comparison across a hundred samples involves a hundred sketches and one comparison step over small files. That inversion is what makes an interactive analysis loop possible at all, since re-running an alignment on raw reads for every parameter change is not viable.

The sketch step is also where the sequence type matters. The command says sketch dna, and the API mirrors the sketch type in the class you construct. The Python library exposes the same functionality as the command line, with FracMinHash as one of the sketch classes alongside the base MinHash.

The support surface is worth noting for adoption. Questions can be raised as issues on GitHub or asked in the project's Gitter chat, and the documentation site carries a quickstart tutorial and a publications page covering sourmash fundamentals. There is a JOSS paper with a DOI, a CITATION.cff file, a Zenodo configuration in .zenodo.json, a codemeta.json for software metadata, and a paper.md and paper.bib pair in the repository, so the tool is set up for formal citation.

The repository also carries a CODE_OF_CONDUCT.rst and a CONTRIBUTING.md, a .pre-commit-config.yaml for linting on commit, and a binder/ directory, which is the BinderHub integration for running the notebooks hosted from the repository.

## The v4 migration, and what a major version costs you

sourmash v4 is a breaking change, and the README puts the warning near the top rather than in a changelog.

The README states that the latest major release is sourmash v4, which has several command-line and Python incompatibilities with previous versions, and points to a migration guide for moving from v3.x to v4.x.

That is the honest way to describe it, and the two-part split matters. Command-line incompatibilities break scripts that shell out to sourmash, and Python incompatibilities break code that imports it. A pipeline that calls sourmash from a shell script and a notebook that imports the library are separate pieces of work, and both need attention.

The version history shows the scale of the release cadence. Recent releases are v4.9.4 on 2025-08-07, v4.9.3 on 2025-06-28 and v4.9.2 on 2025-06-02, while pyproject.toml carries 4.9.5-dev. That is three patch releases in two months for a project with a wide user base, and the fact that the patch numbers move while the minor stays at 4.9 means the 4.x line is still absorbing change.

The last push was on 2026-10-20 and the repository is not archived, so the code is being worked on. But the last published release is from August 2025, which is the number that matters for anything you install from a package index.

The project status badge says the project has reached a stable, usable state and is being actively developed, which is the standard repostatus wording for a 5-production-stable classifier. The pyproject.toml classifiers back that with Development Status :: 5 - Production/Stable, and the intended audience is given as Science/Research with the environment as Console.

The licence detail is worth one note. The repository metadata classifies the licence as Other, a custom licence GitHub cannot classify, while the badge and the pyproject.toml both say BSD 3-Clause. The LICENSE file is present at the root, and BSD 3-Clause is the terms named in both the badge and the manifest, so that is the licence to plan around, though reading the file is the sensible confirmation before shipping it inside a commercial product.

## Where sourmash is the wrong tool

There are three limits, and the first is the one that decides whether you need it at all.

The first is that sourmash does not align. It produces similarity estimates, not alignments, and it cannot tell you where two sequences differ, only how similar they are. That is the correct trade for screening thousands of genomes against a database, and it is useless if your question is which of these three base positions differs between two strains of an organism. For that you need an aligner.

The second is the nature of the estimate. MinHash gives you a similarity with a confidence interval, and the width of that interval depends on the sketch size and the k-mer size. The choice of k is a genuine domain decision with a domain cost: a small k is more sensitive to sequence differences but more prone to false matches from shared short motifs, and a large k is more specific but will miss matches involving divergent sequences. There is no default that is right, and a threshold applied to a similarity score inherits that uncertainty. If you need a yes or no answer about whether two organisms are the same species, a sketch comparison is the wrong instrument.

The third is the dependency weight for a from-source install. Building from source requires Rust and a maturin build, and the Makefile's build target runs pip install -e ., which for a project with a compiled Rust core is a long operation on a cold cache. The pip install path works because wheels are published, but if you need a version that has no wheel, or you are on a platform without one, you are building Rust yourself. The conda path avoids that entirely, which is why the README recommends it.

The honest alternative is Mash itself for the simple case. Mash computes MinHash sketches and distance estimates for genomes, it is a single fast binary with no installation friction, and it is what sourmash takes its name from. The difference in approach is scope: sourmash adds the Python library and the extensible sketch classes including FracMinHash for comparisons across differently sized data sets, the gather command for combinatorial metagenomic profiling, the signature file format, and a growing set of subcommands beyond sketching and distance. If you want a containment estimate between two genomes and nothing else, Mash is less to install and less to learn. If your workflow involves profiling a metagenome against a database, or comparing genomes of very different sizes, sourmash's extra machinery is what you are paying for.

For taxonomy assignment specifically, a k-mer profile is not a taxonomic classification, and sourmash's own topic tags include taxonomic-classification and taxonomic-profiling as separate concerns from the comparison work. If you need to name the organisms in a sample, the taxonomic profile is an input to that question rather than the answer.

## Conclusion

Adopt sourmash if you need to compare sequence data sets quickly, whether genomes, metagenomes or assembled contigs, since the FracMinHash sketches make comparisons between data sets of different sizes tractable. Do not adopt it if you need base-level alignment, since sourmash does not align. Before you upgrade from v3, read the migration guide, because v4 has command-line and Python incompatibilities, and note the last push was on 2026-10-20 with v4.9.4 published on 2025-08-07.

## FAQ

### What is sourmash and what does it do?

sourmash is a k-mer analysis multitool for quickly searching, comparing and analyzing genomic and metagenomic data sets. It computes MinHash sketches of sequences so data sets can be compared by similarity rather than by alignment, and it exposes the same functionality as a Python library and a command-line interface.

### How do I install sourmash?

The recommended method is conda-forge, with conda install -c conda-forge sourmash-minimal, which installs the latest stable version of sourmash 4. pip install sourmash also works. sourmash runs under Python 3.11 and later on Windows, Mac OS X and Linux, and its base requirements are screed, cffi, numpy, matplotlib and scipy.

### What are FracMinHash and sourmash gather used for?

FracMinHash sketching enables accurate comparisons, including ANI, between data sets of different sizes, while sourmash gather is a combinatorial k-mer approach for more accurate metagenomic profiling, finding the reference genomes whose k-mers are all present in a sample.

### What is the basic sourmash workflow?

Sketch the data with sourmash sketch dna *.fq.gz, compare the resulting signatures with sourmash compare *.sig -o distances.cmp -k 31, and render the result with sourmash plot distances.cmp. Sketching happens once per data set and the signatures are small, so the comparison step is cheap to repeat.

### How do I upgrade from sourmash v3 to v4?

Read the migration guide linked from the README, at sourmash.readthedocs.io/en/latest/support.html under migrating from sourmash v3.x to v4.x. The README warns that v4 has several command-line and Python incompatibilities with previous versions, so scripts that call the tool and code that imports the library both need review.

## Sources

- [Issues](https://github.com/sourmash-bio/sourmash/issues)
- [Project website](http://sourmash.readthedocs.io/en/latest/)
- [README](https://github.com/sourmash-bio/sourmash/blob/latest/README.md)
- [Releases](https://github.com/sourmash-bio/sourmash/releases)
- [sourmash-bio/sourmash on GitHub](https://github.com/sourmash-bio/sourmash)

---

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