IGV is a desktop genome browser that most people install rather than build

A desktop viewer for genomic data, not a pipeline

IGV is the Integrative Genomics Viewer, a desktop genome visualization tool for Mac, Windows and Linux. The project description calls it a fast, efficient, scalable visualization tool for genomics data and annotations, and the README calls it simply a desktop genome visualization tool.

The word desktop does the scoping work. This is an application a person opens, points at a genome, and looks at tracks of data with. It is not a library, not a service and not a command line pipeline, and the difference matters for how you evaluate it.

That said, the repository is a substantial Java codebase rather than a small viewer. The primary language is Java, the build is Gradle, and the source lives under src with a separate lib_build directory, a test directory, resources, scripts and an examples directory. The licence is MIT and the homepage is igv.org, and the distribution of the finished application is hosted by the Broad Institute at software.broadinstitute.org/software/igv/download.

The repository is not archived and the last push was on 2026-10-16, and the project publishes no GitHub releases, which is consistent with a desktop application that ships as a downloaded bundle rather than as a package version.

The audience is genomics researchers, clinicians and anyone who needs to inspect a locus with multiple annotation tracks side by side.

Two audiences: the ones who build it and the ones who install it

The README opens the building section by saying the instructions are meant for developers interested in working on the IGV code, and that for normal use the pre-built releases are recommended.

That distinction is the first thing to understand, because the build story is heavier than it needs to be for most users. The prebuilt release is a self-contained bundle; building from source is a development activity.

For the build path there are two hard requirements. IGV requires Java 21 to build and run, with the note that later versions of Java should work but that the project builds and tests on Java 21. And Gradle has to be installed for the platform, with the wrapper in the repository used for the actual commands, and on Windows the wrapper is gradlew.bat rather than gradlew.

On Windows the wrapper is the batch file variant of the same command.

The builds are executed from the IGV project directory and files are created in the build subdirectory. There is also a note that Gradle creates a number of other subdirectories in build, and that these can be safely ignored, which is a small but real warning to anyone who wonders why their working tree is full of directories after a build.

For running the tests there is a dedicated instruction, and it points at a file in the source tree rather than at a wiki page, which tells you the project expects contributors to work from the repository rather than from published documentation.

./gradlew test

The project also keeps a CLAUDE.md file that provides guidance on working with the code and contains general information about the app, including build and run commands, architecture and configuration, which is a useful map for a new contributor.

createDist, the launcher scripts and the folder layout they expect

The distribution target is the piece of the build that matters, because it is what other people install.

./gradlew createDist

Two things stand out. The distribution contains igv.jar together with its required runtime third-party dependencies, and the IGV bundles ship with embedded JREs from AdoptOpenJDK. The second point is the one that changes the installation story: a user is not asked to install a matching Java runtime, because the runtime travels with the bundle.

The launchers are platform specific. IGV is launched with igv.sh or igv_hidpi.sh on Linux, with igv.command on Mac, and with igv.bat on Windows. The separate high-DPI script on Linux is a small signal that the project cares about rendering on high resolution displays.

There is also a command line companion. To run igvtools from the command line you use the script igvtools on Linux and Mac, or igvtools.bat on Windows, with the instructions in igvtools_readme.txt in that directory.

The constraint to know about is stated plainly: the launcher scripts expect this folder structure in order to run IGV. In other words, the distribution directory is not a bag of files you can rearrange, and a user who has moved things around will get a launcher that does not work.

For more detail there is a separate README in the scripts directory with tips about using the launcher scripts, and a dashboard that describes the project structure and dependencies.

Remote data from S3, with three different access routes

The Amazon Web Services section is the part of the README with the most practical value for a user, because it covers getting data into the viewer without downloading it first.

Public data files hosted in Amazon S3 buckets can be loaded into IGV using https endpoints. That is the simplest case and needs no credentials at all.

For anything private the README gives two options, and the difference between them is worth understanding.

The first is authenticated access using s3:// urls, enabled either by turning on OAuth access with Cognito using the UMCCR contributed AWS configuration option, or by setting AWS credentials and region information as the AWS SDK for Java documentation describes. The Cognito route means the user signs in through a browser and the bucket policy recognises that identity. The credentials route means the application carries a key and a region and the SDK signs the request with them.

The Cognito path comes with more moving parts and a different security posture, since the access is granted per user through a token rather than to whatever machine the application runs on. The credentials path is simpler to configure and grants whatever that identity is allowed to do, across every bucket it can reach, not only the one you are looking at. For a shared analysis workstation where several people look at the same data, that distinction is the difference between a per-user grant and a standing one.

The README points to the UMCCR documentation on the backend for more details on using Cognito for OAuth access, and to a frontend guide that walks through provisioning a URL step by step.

Where IGV is the wrong tool

The constraints are clear and they are about shape rather than quality.

First, it is a desktop application. There is no server mode described in the README, and a deployment that has to serve dozens of users from a shared backend is looking at a different class of tool. The repository does contain a preview-application.html and a web directory under examples, so there is web-related material, but the README frames the product as a desktop tool and points at platform-specific launchers.

Second, it is for inspection, not for analysis. The description says visualization tool for genomics data and annotations. If your need is to run a variant calling pipeline, annotate a genome at scale or produce a report, IGV is the wrong instrument, and a script using the command line companion would be a thin substitute for the work you actually need done.

Third, the desktop dependency shapes deployment. A Linux box with no display, a container that needs to render a plot, or a research workflow that has to run headless in a cluster cannot run the application as it ships. The embedded JRE solves the runtime problem, not the display problem.

Fourth, and this is a documentation point rather than a design one, the README is short and the detail sits in a few places. The launcher script notes are in scripts/readme.txt, the test instructions are in src/test/README.txt, the igvtools instructions are in igvtools_readme.txt inside the distribution, and the project structure dashboard is an external link. None of that is a problem for a user who downloads the release, and it is a mild tax for a contributor who prefers a single page.

Editorial conclusion

Researchers and analysts who need to look at genome data and annotations interactively should use IGV, because it runs on Mac, Windows and Linux from a single distribution with the runtime bundled, and it loads remote data from S3 without a manual download step. It is the wrong tool for batch processing, for a web deployment that has to serve many users at once, and for anyone without a desktop. Before adopting, read the launcher script notes in scripts/readme.txt, because the scripts expect a specific folder layout, and check the Java 21 requirement if you are building from source rather than downloading a prebuilt release.

Frequently asked questions

Official sources

1. igvteam/igv on GitHub
2. Issues
3. License: MIT
4. Project website
5. README