# Unicycler: short-read-first hybrid assembly for bacterial genomes

> Unicycler combines an Illumina short-read assembly graph with sparse, noisy long reads to complete bacterial genomes, and it now carries a frank status note from its author saying that long-read-first assembly is often preferable and that a Rust rewrite is planned. It is a tool for bacterial isolates only, and its own documentation tells you when not to use it.

**rrwick/Unicycler** — hybrid assembly pipeline for bacterial genomes

- Repository: https://github.com/rrwick/Unicycler
- Stars: 655 · Forks: 140
- Language: C++
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/rrwick-unicycler

## Three input modes, one best case

The README defines the scope precisely, and the input list is short. Unicycler takes Illumina reads from a bacterial isolate, ideally paired-end although unpaired works, or a set of long reads from a bacterial isolate, either PacBio or Nanopore, or both Illumina and long reads from the same isolate, which is the best case. The three modes map onto three different pipelines. With Illumina-only reads it functions as a SPAdes optimiser. With long-read-only sets it runs a miniasm plus Racon pipeline. Given both, it conducts a short-read-first hybrid assembly. The tool is an assembly pipeline rather than a library, and the repository layout matches that: an unicycler/ package directory, a unicycler-runner.py entry point, setup.py, a Makefile that builds the C++ components, a test/ directory, a sample_data/ directory and a docs/ directory. The primary language is recorded as C++ because the aligner is native code, with the orchestration in Python.

## Why the author now recommends long-read-first instead

The most valuable section in the README is the 2026 update on project status, and it is unusually candid. Unicycler was initially made in 2016, back when long reads could be sparse and very noisy, with early Oxford Nanopore runs generating only 15 times read depth for a single bacterial isolate and most reads carrying a lot of errors, so it was designed to use low-depth and low-accuracy long reads to scaffold a short-read assembly graph to completion. The author calls that approach short-read-first hybrid assembly and says that, assuming the short-read assembly graph is in good shape, Unicycler does this quite well. But things have changed: Nanopore yield is now much higher, making more than 100 times depth obtainable even on multiplexed runs, and read accuracy has improved significantly and is now less of a limitation. High-depth, high-accuracy long reads make long-read-first hybrid assembly, meaning long-read assembly followed by short-read polishing, a viable approach that is often preferable. The author's conclusion is that Unicycler should only be used for hybrid assembly when long-read-first is not an option, that is when long-read depth is low, while still being good for short-read-only bacterial genomes because it produces cleaner assembly graphs than SPAdes alone. Recent releases have focused on compatibility rather than new features.

## Unicycler 2 will be a new Rust codebase

The next phase is announced in the same section, and it is a rewrite rather than an increment. Unicycler 2 will be a major rewrite in a new Rust codebase in a separate repository. It will build its own de Bruijn graph from short reads, long reads or both, rather than relying on SPAdes. The stated benefit of that design is specific: by tracking read paths during graph construction, it should be better able to recover sequence missing from patchy short-read data and resolve repeats without carrying short-read contig errors into the final assembly. Its graph-cleaning steps will be modular, making it easier to adapt the assembler to different data types and sequencing technologies. The two companion tools named in the update are Autocycler for long-read-first assemblies and Polypolish for the short-read polishing half of that approach, both from the same author. The practical consequence for anyone starting work today is that a pipeline decision depends on which of the two philosophies you are in, and the current tool is the one for the low-depth long-read case.

## The reasons to use it, and the reasons not to

The Introduction section lists what the tool is for and what it is not, and the second list is the more useful one for a newcomer. Reasons to use it include that it circularises replicons without the need for a separate tool like Circlator, that it handles plasmid-rich genomes, and that it can use long reads of any depth and quality in hybrid assembly, where 20 times or more may be required to complete a genome but nearly-complete genomes can be made with far fewer long reads. It produces an assembly graph in addition to a contigs FASTA file, viewable in Bandage, it filters out low-depth contigs to give clean assemblies even when the read set has low-level contamination, it has low misassembly rates, it can cope with highly repetitive genomes such as Shigella, and it is easy to use, running with just one command and usually not requiring parameter tinkering. The reasons not to use it are equally clear: you are assembling a eukaryotic genome or a metagenome, since Unicycler is designed exclusively for bacterial isolates; your Illumina and long reads come from different isolates, since Unicycler struggles with sample heterogeneity; and you are impatient, since the tool is thorough but not especially fast.

## How the hybrid method is put together

The table of contents names the method sections, and together they describe the pipeline's logic. For Illumina-only assembly, the method is SPAdes assembly, then multiplicity, which is the removal of repeat copies that the assembler has over-collapsed, then overlap removal, then bridging. For long-read-only assembly the method is miniasm assembly followed by Racon polishing. For hybrid assembly there are three further stages: long-read plus contig assembly, direct long-read bridging, and bridge application, followed by finalisation. The through-line is that the short-read graph is the backbone and the long reads are there to resolve what the short reads cannot, so the output is not a consensus of long reads with short-read correction but a graph that short reads constrain and long reads complete. That is why the tool needs 20 times or more long-read depth to actually close a genome, and why it can still make a nearly-complete assembly with far fewer: the short-read graph has already fixed most of the sequence, and the long reads only have to close the gaps.

## Building it, and the assembler you have to supply

The install has two routes, and the requirement that catches people is that the external assemblers are not bundled. The Makefile in the repository builds the C++ components of Unicycler, and it documents its own example commands:

```bash
#   make (build in release mode)
#   make debug (build in debug mode)
#   make clean (deletes *.o files, which aren't required to run the aligner)
#   make distclean (deletes *.o files and the *.so file, which is required to run the aligner)
```

There are also ways to select a specific compiler or compiler flags, such as make CXX=g++-5 or make CXXFLAGS="-Werror -g3". The Makefile also detects the platform, choosing Mac on Darwin and Linux otherwise, and detects the compiler, checking the compiler help output for clang, g++, c++ or Intel, with a special case for clang because versions earlier than 3.5 will not work with Seqan. The setup.py script installs the C++ components and puts them on the user's PATH, and it insists on Python 3.4 or later, exiting with an error otherwise, and it pulls in setuptools through ez_setup if it is not already present. The README also documents a build-and-run-without-installation path, so the assembler can be run from a build directory without going through the installer.

## Practical options and the tips that matter

The README splits configuration into standard options and advanced options and closes with a Tips section, and the tips are the part that reflects real experience. There is guidance on running time, on necessary read length, on bad Illumina reads, on very short contigs, on chromosomes and plasmid depth, on known contamination, on manual multiplicity, on manual completion, on using an external long-read assembly, and on assemblies with contig overlaps. The manual multiplicity and manual completion entries are worth noting because they point at the two interventions that matter most when a bacterial assembly does not come out clean, and both are things you do by hand rather than by parameter. The contig overlap tip is the other one to read, since assemblies where contigs overlap each other are the case where the long-read bridging stage has to be judged rather than trusted. A repository-level detail worth knowing: the project is GPL-3.0 licensed, the setup.py header states that Unicycler is free software that can be redistributed and modified under the terms of the GNU General Public License, and the repository carries a code_of_conduct.md alongside a test/ directory and sample data, so the project ships its own fixtures and test suite rather than only a manual.

## Conclusion

Unicycler suits a microbial genomics lab that has good Illumina data and only a shallow, noisy long-read run, because its short-read-first design is exactly built for that case and it produces the assembly graph alongside the contigs, which is what makes a closed circle inspectable rather than merely asserted. It is the wrong tool for a eukaryotic or metagenomic project, for a sample where the Illumina and long reads come from different isolates, and increasingly for any project where long-read depth is high, because the author's own 2026 update says it should then only be used for hybrid assembly when long-read-first is not an option. Verify first which sequencing technologies and depth you actually have, check that SPAdes, miniasm and Racon are available on the machine, and note that the newest release is v0.5.1 from 2024-07-25 with the last push on 2026-07-29, and that the successor Unicycler 2 will be a new Rust codebase in a separate repository.

## FAQ

### What input does Unicycler accept?

Illumina reads from a bacterial isolate, ideally paired-end though unpaired works, or a set of long reads from a bacterial isolate, either PacBio or Nanopore, or both from the same isolate, which the README calls the best case.

### When should I not use Unicycler?

The README lists three reasons not to: you are assembling a eukaryotic genome or a metagenome, since Unicycler is designed exclusively for bacterial isolates; your Illumina and long reads come from different isolates, since it struggles with sample heterogeneity; and you are impatient, since it is thorough but not especially fast.

### What is short-read-first hybrid assembly?

It is the approach Unicycler was designed around, using low-depth and low-accuracy long reads to scaffold a short-read assembly graph to completion. The author notes that with today's deep and accurate long reads, long-read-first hybrid assembly is often preferable instead.

### What is Unicycler 2?

The announced next phase, a major rewrite in a new Rust codebase in a separate repository. It will build its own de Bruijn graph from short reads, long reads or both rather than relying on SPAdes, with modular graph-cleaning steps and read-path tracking to recover sequence missing from patchy short-read data.

### How do I install Unicycler?

From source, using the setup.py script, which builds the C++ components and installs them in your PATH, or by building without installing via the Makefile. The setup script requires Python 3.4 or later, and the Makefile detects the platform and compiler, noting that clang versions earlier than 3.5 will not work with Seqan.

## Sources

- [Issues](https://github.com/rrwick/Unicycler/issues)
- [License: GPL-3.0](https://github.com/rrwick/Unicycler/blob/main/LICENSE)
- [README](https://github.com/rrwick/Unicycler/blob/main/README.md)
- [Releases](https://github.com/rrwick/Unicycler/releases)
- [rrwick/Unicycler on GitHub](https://github.com/rrwick/Unicycler)

---

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