Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
January 4, 2017 14:04
April 28, 2014 14:57
September 3, 2014 06:56
December 2, 2013 13:17
September 8, 2021 15:53
April 7, 2023 08:10
December 28, 2013 08:46
January 13, 2022 06:34


Fast and accurante alignment of BS-Seq reads.


As of 2016-08-18, bwa-meth now outputs sam to stdout. It is up to the user to convert to bam. This means that the --prefix and --calmd flags are gone.

Update 2016

bwa-meth is still among (if not the) best aligners for BS-Seq. While it is fairly stable, I will continue to support the alignment part of bwa-meth--fixing any bugs or updating as needed.

There are now several (likely better) alternatives for tabulation and SNP calling than provided here so I will not develop those further.

For tabulation, bias, and plotting, use MethylDackel

For SNP calling (a more modern BisSNP), use biscuit


This works for single-end reads and for paired-end reads from the directional protocol (most common).

Uses the method employed by methylcoder and Bismark of in silico conversion of all C's to T's in both reference and reads.

Recovers the original read (needed to tabulate methylation) by attaching it as a comment which bwa appends as a tag to the read.

Performs favorably to existing aligners gauged by number of on and off-target reads for a capture method that targets CpG-rich region. Some off-target regions may be enriched, but all aligners are be subject to the same assumptions. See manuscript: for details. Optimal alignment is the upper-left corner. Curves are drawn by varying the mapping quality cutoff for alingers that use it.

This image is on real reads and represents an attempt to find good parameters for all aligners tested.

Untrimmed reads comparison

Note that bwa-meth and Last perform well without trimming. scripts for each method are here: I have done my best to have each method perform optimally, but no doubt there could be improvements.


Without installation, you can use as python with install, the command is

The commands: index $REF #Indexes with BWA-MEM (default)
    #OR index-mem2 $REF #Indexes with BWA-MEM2 --reference $REF some_R1.fastq.gz some_R2.fastq.gz > some.output.sam

will create some.output.bam and some.output.bam.bai. To align single end-reads, specify only 1 file.

See the full example at:


The following snippet should work for most systems that have samtools and bwa installed and the ability to install python packages. (Or, you can send this to your sys-admin). See the dependencies section below for further instructions:

    # these 4 lines are only needed if you don't have toolshed installed
    tar xzvf toolshed-0.4.0.tar.gz
    cd toolshed-0.4.0
    sudo python install

    cd bwa-meth-master/
    sudo python install

After this, you should be able to run: and see the help.


bwa-meth depends on

  • python 2.7+ (including python3)

    • toolshed library. can be installed with:

      • easy_install toolshed or
      • pip install toolshed
    • if you don't have root or sudo priviledges, you can run python install --user from this directory and the executable will be at: ~/.local/bin/

    • if you do have root or sudo run: [sudo] python install from this directory

    • users unaccustomed to installing their own python packages should download anaconda: and then install the toolshed module with pip as described above.

  • samtools command on the $PATH (

  • bwa mem from: OR bwa-mem2 from:



One time only, you need to index a reference sequence. index $REF #Indexes with BWA-MEM (default)
#OR index-mem2 $REF #Indexes with BWA-MEM2

If your reference is some.fasta, this will create some.c2t.fasta and all of the bwa indexes associated with it.

Align --threads 16 \
     --reference $REFERENCE \
     $FQ1 $FQ2 > some.sam

The output will pass will have the reads in the correct location (flipped from G => A reference).

Handles clipped alignments and indels correctly. Fastqs can be gzipped or not.

The command above will be sent to BWA-MEM or BWA-MEM2 to do the work as something like:

bwa mem -L 25 -pCM -t 15  $REFERENCE.c2t.fa \
            '<python c2t $FQ1 $FQ2'


bwa-mem2 mem -L 25 -pCM -t 15  $REFERENCE.c2t.fa \
            '<python c2t $FQ1 $FQ2'

Index from BWA-MEM or BWA-MEM2 is auto detected and the corresponding aligner is chosen.

So the converted reads are streamed directly to bwa and never written to disk. The output from that is modified by bwa-meth and streamed straight to a bam file.