Picard is the command line layer over HTSJDK for sequencing data

A command line layer over one Java library

Picard is a set of Java command line tools for manipulating high-throughput sequencing data and formats, and the readme is clear about the layering.

Picard is implemented using the HTSJDK Java library to support accessing file formats that are commonly used for high-throughput sequencing data such as SAM and VCF. For the lower level core contracts, in this case the file format specifications, the readme points at the samtools specifications.

So the architecture is that HTSJDK does the hard part, which is reading and writing these container formats correctly, and Picard is a set of well known operations on top of it, each one a subcommand. That is why the tools are used so widely in pipelines, and why a lot of what people call Picard is really HTSJDK.

The implementation is Java, the licence is MIT, and as of version 3.0 Picard requires Java 1.17. The last push was on 2026-07-31 and the recent releases are 3.5.0 from 2026-07-31, 3.4.0 from 2025-04-13 and 3.3.0 from 2024-10-09.

The support model is also worth knowing about early. For user questions the readme asks you to look for answers and ask first in the GATK forum, and the Picard and GATK projects are siblings at the Broad Institute, which is why the same organisation maintains both.

Building one runnable jar

The build is Gradle with a wrapper, and the interesting target is the shadow jar.

First, clone the repository.

git clone https://github.com/broadinstitute/picard.git
cd picard/

Then, to build a fully packaged, runnable Picard jar with all dependencies included.

./gradlew shadowJar

The resulting jar is in build/libs, and the run command is either of the two forms, using the plain name or the versioned one.

java -jar build/libs/picard.jar

There is a second target for the other case. To build a jar containing only Picard classes, without its dependencies, run ./gradlew jar, and to clean the build directory, ./gradlew clean.

The split between the two artefacts is the usual one and it is worth understanding before you distribute anything. The shadow jar is self contained and runs anywhere with a Java runtime, which is why it is the one people put in a container or download onto a cluster node. The plain jar is a library artefact, and it is what you want if you are embedding Picard in a Java application and managing the HTSJDK version yourself.

Two test suites, because there are two command line parsers

The test section is short, and the split is unusual enough to be worth understanding.

To run all tests, the command is ./gradlew test. To run a specific test, there are two separate tasks.

./gradlew legacyTest --tests "*TestClassName*"

./gradlew barclayTest --tests "*TestClassName*"

The explanation is one line. Running legacyTest uses the legacy command line parser while barclayTest uses the new parser.

That is the practical consequence of a project in the middle of a migration. Picard has two command line parsing implementations in the tree, one inherited from its history and one newer, and the tests have to pass against both, because both are still in use by somebody's pipeline. A bug that reproduces only under one of the parsers will not be caught by the general test task, so the specific tasks exist to let you narrow it down.

If you are debugging a Picard argument problem, running the task that matches the parser you are using is the first thing to do.

Swapping the HTSJDK version, which is a supported activity

There is a whole section of the readme about changing the released version of HTSJDK that Picard depends on, and the fact that it is documented at that length tells you how much the dependency moves.

To switch to a different released version, you open build.gradle and edit the VERSION in the line that sets the htsjdkVersion property, and you open a pull request with the change. The property is read from a system property, so it can also be overridden on the command line.

final htsjdkVersion = System.getProperty('htsjdk.version', 'VERSION')

For development there are two documented routes for building against a version that is not released. The first is to take a continuous snapshot of HTSJDK's master branch from the Broad artifactory, where the snapshots are published, and select the version you want, for example one with a git describe style suffix, and then run ./gradlew shadowJar with the htsjdk.version property set to that version.

The second route is for a version that has not yet been merged. You clone HTSJDK yourself, check out the tag or branch you want, run ./gradlew install printVersion in that clone to install the version to your local Maven repository, note the version number that is printed, and then build Picard against it the same way.

The fact that printVersion is a Gradle task rather than something you read off a file is a small kindness, because the version string for a snapshot is exactly the thing you will otherwise paste wrong.

Reading from cloud storage, and the GATK shortcut

Picard has limited support for reading from path providers, and the limits are stated plainly. Currently only Google's api is supported, and only a few tools support it.

To run with this support you compile the cloudJar target with Gradle.

./gradlew cloudJar

And then you run picard with the cloud jar instead of the standard one.

java -jar build/lib/picardcloud.jar CrosscheckFingerprints \
   I=gs://sample1.vcf \
   I=gs://sample2.vcf \
   CROSSCHECK_BY=FILE \
   H=Haplotype_db.txt \
   O=crosscheck.out

The alternative is to run the tool through GATK, which bundles the Google Cloud jar and should thus just work.

So there are three ways to get at the same functionality. The cloud jar, the GATK distribution, and the plain jar if you are willing to configure the cloud libraries yourself. The readme's phrasing about the GATK route is characteristic of the project, and the GATK download is linked.

The limited support is the part to remember. If your pipeline reads from object storage, the tool you reach for depends on the specific subcommand, and the answer is in the documentation rather than in the code.

The container image carries an R installation

The Dockerfile is two stages on a Java 17 base, and the final image contains something you would not expect.

The base is eclipse-temurin:17-jdk, and the build stage installs git, because the Gradle build needs it, and then copies the whole repository into the container and runs the wrapper with clean, printVersion and shadowJar.

The final stage starts from the same base and then does something specific.

FROM ${BASE_DOCKER} as final

RUN apt-get update && \
    apt-get --no-install-recommends install -y \
        r-base &&\
    apt-get clean autoclean && \
    apt-get autoremove -y

So the runtime image carries a full R installation, which is there because some Picard tools and the wider Broad genomics stack call into R for statistics. The jar is copied in from the build stage, a working directory is created, and the maintainer is recorded as Broad Institute DSDE with their engineering address.

That is a large image for a command line tool, and it is a good illustration of the difference between the library and the environment around it. The Picard code itself needs a Java runtime and nothing else; the container is a convenience for the workflows that surround it.

Versioning is still settling, and how to cite it

The last section of the readme is about how to refer to the project, and it contains the versioning caveat that matters most to a user.

Picard is migrating to semantic versioning. The plan is to adhere to it strictly and bump the major version whenever there are breaking changes to the API, but until the project more clearly defines what constitutes the official API, clients should assume that every release potentially contains at least minor changes to public methods.

That is an unusually direct warning, and it is the sort of thing that should shape how you pin the version in a pipeline. A major version bump is not a signal that something broke, and a minor bump is not a signal that nothing did.

For citing, the request is to cite the repository when using the tools in a publication, with the given BibTeX entry pointing at the GitHub repository, and the readme also notes that identifiers from software registries are increasingly accepted by journals, in the form of biotools:picard_tools or the RRID SCR_006525.

The repository layout supports the project rather than the library, with src/ for the tools, testdata/ for the test files, docs/ for the documentation, scripts/ and etc/ for the auxiliary material, a build.gradle and a build.xml for the two build systems, a gradlew wrapper, a settings.gradle, a Dockerfile and a build_push_docker.sh, and a gradle/ directory.

Editorial conclusion

Adopt Picard for any genomics pipeline that touches alignment or variant files, because it is the reference implementation of the format operations and the HTSJDK underneath is the reference reader. Do not assume its command line is stable, since the project is still migrating to semantic versioning and asks clients to assume every release may change public methods. Verify first that your Java is 1.17 or newer, which the version 3.0 requirement introduced, and that the HTSJDK version it builds against is the one you need, since that dependency is the part that is swapped during development and can differ from a published release.

Frequently asked questions

Official sources

1. broadinstitute/picard on GitHub
2. License: MIT
3. Project website
4. README
5. Releases