10x Genomics

Converting 10x BAM Files to FASTQ

bamtofastq is a tool for converting 10x BAMs produced by cellranger, cellranger-atac, cellranger-arc, cellranger-dna, spaceranger or longranger back into FASTQ files that can be used as inputs to re-run analysis. The FASTQs will be emitted into a directory structure that is compatible with the directories created by the mkfastq tool.

  BAMs produced for TCR or BCR data, by aligning to a V(D)J reference with cellranger vdj or cellranger multi, are not supported by bamtofastq.

Special tags included by 10x pipelines are required to reconstruct the original FASTQ sequences correctly. If your BAM file lacks the appropriate headers, you will get an error message: WARNING: no @RG (read group) headers found in BAM file.

A common problem is using an 'edited' BAM file from SRA, which are missing tags produced by Cell Ranger.

You need the BAM file from the section labelled 'Original Format' on the SRA downloads page. Here is an example of a SRA dataset with the 'Original Format' BAM available

Only the 'Original Format' BAM files have the necessary BAM tags preserved to work correctly with bamtofastq.


We created bamtofastq to help users who want to reanalyze 10x data and only have access to 10x BAM files. (e.g. Some customers want to store BAM files only. Others might have downloaded our BAM data from NCBI SRA). 10x pipelines require sequencer FASTQs (with embedded barcodes) as input. The location of the 10x barcode varies depending on product and reagent version. bamtofastq determines the appropriate way to construct the original read sequence from the sequences and tags in the BAM file.

Download & Installation

bamtofastq is available for Linux and is compatible with RedHat/CentOS 5.2 or later, and Ubuntu 8.04 or later.

Download bamtofastq 1.3.2

We recommend upgrading to bamtofastq 1.3.2—it is now multi-threaded and is compatible with Cell Ranger ATAC BAM files.

bamtofastq is a single executable that can be run directly and requires no compilation or installation. Place the executable file in a directory that is on your PATH, and make sure to chmod 700 to make it executable.

Note, MacOS versions of bamtofastq are available on the Github Page for bamtofastq

Running the Tool

10x BAMs produced by Cell Ranger v1.2+, Cell Ranger ATAC v1.0+, Cell Ranger DNA v1.0+, and Long Ranger v2.1+ contain header fields that permit automatic conversion to the correct FASTQ sequences. BAMs produced by older 10x pipelines may require special arguments or have some caveats, see below for details. Run times for full-coverage WGS BAMs may be several hours.

The FASTQ files emitted by bamtofastq contain the same set of sequences that were input to the original pipeline run, although the original order will not be preserved. 10x pipelines are generally insensitive to the order of the input data, so you can expect nearly identical results when re-running with bamtofastq outputs.


Threads to use for reading BAM file. Default: 4
Optional. Only include read pairs mapping to locus. Use chrom:start-end format.
Number of reads per FASTQ chunk. Default: 50000000
Convert a BAM produced from GemCode data (Longranger 1.0 - 1.3)
Convert a BAM produced by Longranger 2.0
Convert a BAM produced by Cell Ranger 1.0-1.1
Only include BX values listed in text file L. Requires BX-sorted and indexed BAM file (see Long Ranger support for details).
Show the help screen.

Known Issues

The latest versions of cellranger, cellranger-atac, cellranger-dna and longranger generate BAM files that automatically reconstruct complete FASTQ files representing all input reads. BAMs produced by older versions of cellranger and longranger have some caveats, listed below:

PackageVersionPipelinesExtra ArgumentsComplete FASTQs
Cell Ranger1.3+countnoneYes
Cell Ranger1.2countnoneReads without a valid barcode will be absent from FASTQ. (These reads are ignored by Cell Ranger)
Cell Ranger1.0-1.1count--cr11 Reads without a valid barcode will be absent from FASTQ. (These reads are ignored by Cell Ranger)
Cell Ranger ARC1.0.0+countnoneAny sequenced bases in the I5 index read that are not part of the 10x barcode are dropped from the FASTQ output.
Cell Ranger ATAC1.0.0+countnoneAny sequenced bases in the I5 index read that are not part of the 10x barcode are dropped from the FASTQ output.
Cell Ranger DNA1.0.0+cnvnoneYes
Long Ranger2.1.3+wgs, targeted, align, basicnoneYes
Long Ranger2.1.0 - 2.1.2wgs, targetednoneYes
Long Ranger2.0wgs, targeted--lr20Yes
Long Ranger2.0.0 - 2.1.2align, basicNot SupportedN/A
Long Ranger1.3 (GemCode)wgs, targeted--gemcodeReads without a valid barcode will be absent from FASTQ. This will result in a ~5-10% loss of coverage.