medaka: neural network consensus for nanopore reads

Basecalls in, consensus out, and the pileup that makes it work

medaka is a tool to create consensus sequences and variant calls from nanopore sequencing data, and the mechanism is described in one sentence. The task is performed using neural networks applied to a pileup of individual sequencing reads against a reference sequence, most commonly either a draft assembly or a database reference sequence.

That is the whole idea. Nanopore reads are noisy, and the traditional way to fix them is to align them to the reference, call a consensus at each position and accept the result. medaka instead trains a network that looks at the pileup and decides, per position, what the base is.

The claims it makes are specific and quantified. It provides state-of-the-art results outperforming sequence-graph based methods and signal-based methods, whilst also being faster. It is 50X faster than Nanopolish and can run on GPUs. It has improved accuracy over graph-based methods such as Racon. And it requires only basecalled data, meaning a fasta or fastq file, with no signal-level access needed.

That last point is the practical significance of the design. Signal-based methods use the raw current traces from the flow cell, which means they need the original sequencing run output and a signal-to-basecaller path. Working from basecalls means medaka can be run on data that was basecalled elsewhere, archived, or received from a sequencing facility, which is the normal state of most nanopore data in practice.

The feature list also mentions that it includes extras for implementing and training bespoke correction networks. That is worth noting because it means the tool is not only a consumer of trained networks but a way to train your own.

The tool works on Linux and macOS, and the licence is the Oxford Nanopore Technologies PLC Public License Version 1.0, recorded as a custom one that GitHub could not classify. The last push was on 2026-05-20 and the release was v2.2.2 the same day.

Three install routes, and the one the project does not support

Medaka can be installed in one of several ways, and the differences between them are more than a matter of preference.

The pip route is the official one. Official binary releases are available on PyPI:

    pip install medaka

On contemporary Linux and macOS platforms this installs a precompiled binary, and on other platforms a source distribution may be fetched and compiled. The recommendation is to use it within a virtual environment:

    python3 -m venv medaka
    . ./medaka/bin/activate
    pip install --upgrade pip
    pip install medaka

The important consequence of the pip route is that you have to supply four external binaries yourself: samtools, minimap2, tabix and bgzip, and place them within the PATH. The versions recommended are samtools, bgzip and tabix at 1.14 or newer and minimap2 at 2.17 or newer, since those are the ones used in the development of medaka.

The conda route bundles the extra tools, so an end-to-end correction workflow works out of the box:

    conda create -n medaka -c conda-forge -c nanoporetech -c bioconda medaka

But there is a warning attached to it, and it is the kind of warning that matters. The bioconda medaka packages are not supported by Oxford Nanopore Technologies.

So the conda install is convenient and the binaries it gives you are not the ones the developers stand behind. The reason is visible in the Makefile, which builds a cache of the binaries and can just be copied for CI, and which lists samtools, minimap2, tabix, bgzip and bcftools. The conda channel builds them, and the difference in version or patch level is what makes the support statement necessary.

The third route is building from source, and it comes with a clear warning about when to use it. This method is useful only when the above methods have failed, as it will assist in building various dependencies, and the developers are unlikely to be able to provide further assistance if you install this way.

The source route needs a set of prerequisite libraries, listed for Ubuntu as bzip2, a compiler, zlib and lzma and libffi and ncurses and curl and gnutls development packages, OpenSSL, make, cmake, wget and Python development headers. It also requires git LFS to be installed and set up before cloning the repository.

The source build then reduces to a clone, a make install and an activation:

    # Note: certain files are stored in git-lfs, https://git-lfs.github.com/,
    #       which must therefore be installed first.
    git clone https://github.com/nanoporetech/medaka.git
    cd medaka
    make install
    . ./venv/bin/activate

And the advantage of that route is stated plainly: using this method both samtools and minimap2 are built from source and need not be provided by the user.

GPU support is the default, and the CPU variant used to be a different package

Since version 2.0 medaka uses PyTorch, and prior versions used TensorFlow. That single change explains most of the installation complexity, because PyTorch is the package that carries the CUDA and cuDNN dependency.

The default version of PyTorch installed when building from source or installing through pip can make immediate use of GPUs via NVIDIA CUDA. The caveat is that the torch package is compiled against specific versions of the CUDA and cuDNN libraries, so users are directed to the PyTorch installation pages for further information. cuDNN comes from the cuDNN Archive and CUDA from the CUDA Toolkit Archive.

If the GPU capability is not required, medaka can be installed with a CPU-only version of PyTorch that does not depend on the CUDA libraries, using the extra index URL for the CPU wheels if using the prebuilt packages, or the MEDAKA_CPU environment variable set to one if building from source.

The recent history of the CPU package is a small but instructive detail. The medaka-cpu package has been deprecated for versions above 2.2.0 because these are now identical to the standard medaka package. To upgrade an existing virtual environment, the instruction is to remove the medaka-cpu package and install medaka instead.

So the split-package approach that existed to avoid pulling CUDA onto a CPU machine has been collapsed into one package, and the extra index URL is now the way to get a CPU-only torch.

The practical advice in the documentation is that if you are using medaka exclusively on CPU and do not need the ability to run on GPU, the CPU-only version may be what you want.

There is also a usage note about memory. Depending on your GPU, medaka may show out of memory errors when running. To avoid these the inference batch size can be reduced from the default value by setting the batch size option when running medaka_consensus, with a value of 100 given as suitable for 11Gb GPUs.

That is the practical shape of the GPU story. The accelerator is well supported, the batch size is the knob for memory pressure, and the CPU path is a one-flag change.

The dependency pins are a record of what broke

The requirements file is short, and the comments attached to it are more informative than the list itself.

cffi
edlib
h5py
intervaltree
numpy>=2.0
ont-mappy
ont_fast5_api
ont-parasail
pysam>=0.16.0.1,<=0.23.0
pyspoa>=0.2.1
torch~=2.9

The file opens with a note that comments are added to keep track of why particular versions are used, and that they are not to be put on the same line because the continuous integration likes to fiddle with them occasionally.

That is a small admission that the version pins are not immutable, which is consistent with the pins themselves. numpy is held at 2.0 or newer. pysam is bounded on both sides, with the comment that 0.16.0 is broken and various others too, and a second comment explaining that 0.23.1 onwards is broken for test coverage on Python 3.13, with a link to the issue. And pyspoa is held at 0.2.1 or newer because 0.2.0 has a min_coverage parameter.

So every one of the bounds in that file exists because of a specific failure, and two of the three have a comment saying so. That is worth reading as a signal about the state of the dependency stack, and as a reason to pin your own environment rather than resolve fresh.

The rest of the list is the usual scientific Python set. cffi for the C interface, edlib, h5py for the HDF5 files that nanopore data comes in, intervaltree, ont-mappy for the mapping library, ont_fast5_api for the fast5 access, ont-parasail for the pairwise alignment, packaging, requests, tensordict, toml, torch at roughly 2.9, tqdm and wurlitzer.

Three of those are Oxford Nanopore's own packages, and they are the marker of how tightly this project is coupled to the nanopore data format. ont-mappy is the mapper, ont_fast5_api reads the fast5 files, and ont-parasail does the alignment, so a medaka installation carries the nanopore stack with it whether or not you need the signal files.

The build system is setuptools with wheel and cffi as the build requirements, and the setup.py does something worth noting. It loads the options module separately, by locating the file and using importlib to execute it, so that the package can decide which models to ship, and it has a check_model_lfs function that determines whether the data files look like LFS stubs and fails if they are, unless the distribution environment variable says otherwise.

That check exists because the models are large binary files stored in Git LFS, and a clone without LFS set up would otherwise produce a package with stub files that fail confusingly at run time. The build turns that into an error at install time instead.

Running it, and what the container image is for

medaka runs through its default settings with the medaka_consensus program. An assembly in fasta format and basecalls in fasta or fastq formats are required, and the program uses both samtools and minimap2. If medaka was installed using the from-source method these will be present within the medaka environment, otherwise they will need to be provided by the user.

The usage example is a sequence of shell steps that activate the environment, determine the processor count and set the basecalls variable, and it is worth noting the shape of it. The workflow is a pipeline of separate tools rather than a single command, and medaka sits at the end of it.

That is the reality of the design. The pileup has to be built by samtools, the reads have to be mapped by minimap2, and the network does the correction and the variant calling. The Makefile in the repository confirms the division by listing exactly those tools as the binaries it caches.

The repository layout reflects the same split. There is a medaka/ directory for the package itself, a src/ directory, a scripts/ directory, a conda/ directory for the conda packaging, an images/ directory, a submodules/ directory for the vendored sources, and a build-wheels.sh script alongside build.py and setup.py.

The Makefile is where the build system detail lives. It detects the operating system and the architecture, and the architecture branch is where the tuning happens: on arm64 the tune flags are empty and the minimap2 arguments enable the arm Neon path, while on x64 the tuning is set for the haswell target and the separate argument variable is empty. There is a macOS arm branch that points the HDF5 directory at the Homebrew cellar path for version 1.10.

The deflate handling is the other thing the Makefile does carefully. Setting the deflate flag to one builds with libdeflate, which requires setting the library path at runtime, and the comment notes that this does not apply to the wheel, which bundles the library along with curl, crypto and lzma.

The top level also carries a .gitlab-ci.yml and a .github/ directory, so the project runs continuous integration on both platforms, plus a .coveragerc with a coverage failure threshold set in the Makefile at 80, and a CHANGELOG.md.

The releases are recent and regular. Version 2.2.0 came in December 2025, 2.2.1 in April 2026 and 2.2.2 in May 2026.

Editorial conclusion

medaka suits a lab with a nanopore sequencer and a pileup workflow, since it needs only basecalled files rather than signal and it replaces the align and call steps with a single model, and the claimed speed over Nanopolish is what makes it practical on a routine run. It does not suit you if you want a self-contained install with no external tools, because the pip route leaves samtools, minimap2, tabix and bgzip to you. Before you deploy it, read the requirements comments, since the version bounds exist because of specific breakages, and check the model file handling, because the shipped networks live in Git LFS and a clone without LFS produces a package that fails at run time rather than at install.

Frequently asked questions

Official sources

1. Issues
2. nanoporetech/medaka on GitHub
3. Project website
4. README
5. Releases