FastQC and the pass, warning and fail report on a FastQ file

What the checks are for, and what they deliberately do not say

FastQC takes a FastQ file and runs a series of tests on it to produce a report, and each test is flagged as a pass, a warning or a fail depending on how far it departs from what a normal large dataset without significant biases would look like.

That three-state vocabulary is the core of the design, and the README is unusually careful about how to read it. It stresses that warnings or even failures do not necessarily mean there is a problem with the data, only that it is unusual, and that the biological nature of your sample might mean you would expect this particular bias in your results. A failed check is a prompt to look, not a verdict.

The tool is not tied to any specific sequencing technique. The README names genomic sequencing, ChIP-Seq, RNA-Seq and BS-Seq among the experiment types it can be pointed at, and the reason is structural rather than incidental. A FastQ file carries a base call and an encoded quality value per base, and the quality encodings and bias profiles that a test flags on are generic properties of a run rather than properties of one assay. That generality is what lets one binary serve half a dozen assay chemistries.

The audience is whoever owns the sequencing data before the first alignment, which in practice means a bioinformatician or a sequencing facility engineer. The value proposition is stated plainly in the README: before proceeding with analysis of a data set it is a good idea to run some basic quality control checks on the raw data, so that hidden problems are not carried forward into stages where they are harder to detect.

The reference implementation for what the checks look like is the paired-end data FastQC itself uses, since the tool ships with its own example data in the test directory.

Two ways to run it: a window and a report generator

FastQC can be run as an interactive graphical application that lets you view results for multiple files in a single application, or it can be run non-interactively, for instance as part of a pipeline, in which case it generates an HTML report for each file it processes.

That split determines how you install it and where the tool belongs in your workflow. The interactive form is for a person at a terminal with a small number of files to look at. The batch form is for an unattended pipeline, and the deliverable is a file on disk rather than a screen.

The report is the durable artefact in both cases. It summarises the results of the analyses, and it is designed to be read after the fact, which is the point for a pipeline: the HTML file can be kept next to the data, attached to a sample sheet, or opened later when someone asks why a run behaved oddly. The interactive window is a convenience layer on top of the same underlying computation.

The choice of Java as the implementation is worth noting for the operational side. The README says FastQC is a cross-platform application written in java, and that in theory it should run on any platform with a suitable Java runtime environment. The theory is qualified immediately afterwards: it has only been tested on Windows, MacOSX and Linux running the Oracle v1.6 to 1.8 JREs, and the README asks to be told what happens if you try other platforms or JREs, pointing to the detailed instructions in the INSTALL.txt document for getting a suitable Java version.

That is an old caveat. The wording dates from an era when a Java runtime was not a given on every analysis machine, and the tested range stops at version 1.8. It is a real consideration for a deployment today, and it is one of the first things to check rather than discover.

A cross-platform application with no compiled dependencies also means the operational footprint is a JAR set and a runtime, which is comfortable in a container image.

The source tree: Ant, bundled jars and a Perl launcher

The repository is a Java project built with Ant, and the layout tells you what it depends on.

There is a build.xml at the root and the source sits under net/, org/ and uk/, which are the conventional package roots for the parts of the codebase that came from different sources. The lib/ directory holds third-party code. The Configuration/ directory holds the check definitions and thresholds, and the Templates/ directory holds the report templates, so the layout separates what a check computes from how the result is rendered. Help/ holds the documentation assets shown in the application, and test/ holds the test suite.

Several jars are committed directly in the root rather than resolved at build time: cisd-jhdf5.jar with its own LICENSE_JHDF5.txt, commons-compress-1.28.0.jar, commons-io-2.22.0.jar and htsjdk.jar. htsjdk is the library that gives the tool BAM and CRAM reading, which is why the README says the analyses run on files in fastq or bam format rather than on FastQ alone. Committing the jars is what lets the build work without network access, at the cost of a tree that needs manual updating when a dependency version changes.

The launcher story is also visible at the root. There is a fastqc script and a fastqc.pl Perl script, plus run_fastqc.bat for Windows and a fastqc_icon.ico. The Perl script is the traditional entry point on Unix-like systems and the batch file covers Windows.

There is a .devcontainer/ directory at the root, which suggests the project is set up for development inside a container, and a RELEASE_NOTES.txt file, which is where a project of this vintage records what changed between versions.

Where the compiled program actually comes from

The README carries an explicit note that this GitHub project page contains the source code for the application and is only really useful to people wanting to develop new functionality or trace bugs in FastQC. If you just want to run the program, it directs you to the project web page at bioinformatics.babraham.ac.uk, where you can download the compiled packages for Windows, OSX and Linux.

That distinction is easy to miss and it matters for adoption. A repository tagged as a source distribution is not a place to clone when you want a working tool, and a user who clones it and tries to run it will hit the Ant build and the bundled jars rather than an application.

Installation in the README is therefore a pointer rather than a procedure: see the project web page and the installation instructions in INSTALL.md in this repository. Both routes are named, and INSTALL.md is where the runtime requirements live, including how to get a suitable Java version.

For a pipeline operator this is a small annoyance and nothing more. You download the compiled package for your platform, point it at the FastQ files, and take the HTML reports. For a developer who wants to change a threshold, add a check or fix a bug, the source tree with its Ant build, the Configuration directory and the Templates directory is the working environment, and the issue tracker and the maintainer's email address are both given in the README.

The licence is GPL-3.0, with the LICENSE file at the repository root. For a tool that most people run as a downloaded binary rather than embed, the practical implication is limited, but it does mean that distributing a modified FastQC carries the corresponding source obligation.

The check battery and the limits of a pass or fail verdict

FastQC's own example data is paired-end data, and the checks are defined in the Configuration/ directory rather than in code, which is the design that makes them adjustable without recompiling.

The serious limitation is not any single check, it is the nature of the output. A verdict of pass, warning or fail is a comparison against expectations calibrated for a normal large dataset with no significant biases, and the README is explicit that unusual is not the same as wrong. That means a human has to look at every warning and decide, and in a pipeline over thousands of samples, someone has to build the review process on top of the tool.

There is also no documented machine-readable output. The stated interfaces are the HTML report per file and the interactive application, and the README does not describe a JSON or tabular output format. If you want to gate a pipeline on a specific check, you are scraping the report or reimplementing the check outside the tool.

The other limitation is the input format boundary. FastQC reads FastQ and BAM, and it works on raw reads with their per-base quality values. It is not a tool for aligned data, for variant calls, or for any stage after alignment, so it cannot replace the later quality control in a modern workflow. It occupies one position, the first one, and it does that position well.

The runtime caveat compounds this in practice. A quality control tool that sits at the very front of every pipeline is exactly the kind of tool that has to work on whatever Java is installed on the analysis host, and the tested range in the README stops at Oracle JRE 1.8.

Version history: a long gap, then a new release

The release history is worth reading closely, because the gaps are the story.

The tagged releases are v0.12.0 and v0.12.1, both dated 2023-03-01, and then v0.13.0 on 2026-10-02. So there is a three-and-a-half year stretch between the last of the 0.12 releases and the 0.13 release, and the repository has no GitHub releases beyond those tags.

The repository is not archived, and the last push was on 2026-10-07, a few days after the 0.13.0 tag, so the 0.13 release is recent rather than a historical curiosity.

The version numbering tells you where the project sits. It is a 0.x release, which by convention means the interface is not frozen, and a single 0.13.0 after a long gap reads as a substantial release rather than an increment. The RELEASE_NOTES.txt file in the repository is where the detail would be, and for anyone evaluating the upgrade from 0.12, that file is the place to read first.

Two consequences follow for an adopter. First, a jump from 0.12 to 0.13 crosses a long period in which the underlying libraries moved, and the committed jars in the repository root, commons-compress at 1.28.0 and commons-io at 2.22.0 among them, are pinned to versions far newer than the 0.12 line would have used. Second, because the compiled packages are distributed from the project web page rather than from GitHub releases, the version you run is the version of that download, and the two should be checked against each other.

Editorial conclusion

FastQC is a good fit for a sequencing pipeline that needs a first-pass sanity check on raw data before anything downstream runs, because the checks are fixed, the thresholds are documented and the output is a per-file HTML report that drops straight into a pipeline. It is a poor fit if you need the output as structured data for programmatic thresholds, since the documented interfaces are the HTML report and the interactive application, and it is a poor fit if you need the tool to run on a modern JVM without checking, because the README says it was only tested against Oracle JRE 1.6 to 1.8. Before adopting, read INSTALL.md in this repository for the runtime requirements, and note that the compiled Windows, macOS and Linux packages are downloaded from the project web page rather than built from here.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. s-andrews/FastQC on GitHub