Skip to main content

JBrowse desktop quick start

In this guide, we'll install JBrowse desktop, open a genome, add a track, and save a session, all from the GUI, with no command line or web server required. Desktop opens files straight off your local filesystem. For a hosted browser, see the web quick start; to embed a genome view in your own web app, see embedded components.

Installing JBrowse desktop

Go to the download page and download the installer for your platform, or grab the latest release directly from GitHub releases.

Installing on Windows

Download the latest Windows installer executable (.exe) and double-click it to install and open JBrowse.

Installing on macOS

Download the latest macOS release artifact (.dmg), open it, then drag JBrowse to Applications.

Installing on Linux

Download the latest Linux AppImage release (.AppImage) and start it in one of two ways.

In the terminal, make the file executable, then run it:

# Make the AppImage file executable, only need to do this once
chmod a+x jbrowse-desktop-*-linux.AppImage
# Run!
./jbrowse-desktop-*-linux.AppImage

Or in your file explorer (steps may vary by distribution):

  • right-click the AppImage and open "Properties"
  • go to the "Permissions" tab
  • check "Allow executing file as program"
  • double-click the AppImage to launch JBrowse

The start screen

After starting JBrowse Desktop, you'll see a start screen with two panels:

The JBrowse desktop start screen. The left panel launches new sessions; the right panel lists recently opened ones.

The left panel, "Launch new session", starts a new session from your own genome or a pre-loaded one:

  • Open new genome loads a custom genome from local files or URLs (see Opening a genome).
  • Show all available genomes browses and launches from a searchable table of publicly available reference genomes.
  • Favorite genomes and Quickstart list are one-click launchers for genomes you've starred or saved.

The right panel, "Recently opened sessions", holds sessions you've saved, plus autosaves. Click a session name to reopen it (see Saving and reopening sessions).

Opening a genome

Open new genome brings up the "Open genome(s)" dialog, and what you give it there becomes a new session on that assembly.

Opening a genome from your own files. Open new genome (1) brings up the dialog, and the sequence file goes onto its drop area (2).

The dialog is drop-first. Drop your sequence file (a FASTA, bgzip-compressed FASTA, or 2bit, along with any .fai/.gzi index files) onto the drop area, or click it to browse. To load from the web, click Open from a URL and paste your file URLs, one per line. JBrowse classifies each file, and once it recognizes a sequence it shows a confirmation card with a Genome name field (e.g. hg38). The drop area and the URL box stay where they are, so a .fai you forgot can go in after the sequence is already recognized. JBrowse names any file it can't place or can't use with the format it detected.

If a filename doesn't match the conventions JBrowse detects, it offers Enter details manually, opening a form with a Format dropdown:

  • FASTA with index (.fa + .fai)
  • Compressed FASTA (.fa.gz + .fai + .gzi) (bgzip-compressed)
  • FASTA (automatically indexed) - a plain FASTA with no index. JBrowse builds one on open, reading the whole file (and downloading all of it first if it's a URL), so this can take a while on a large genome. Cancel stops it — supply a .fai and choose "FASTA with index" to skip the step entirely
  • 2bit file (.2bit)

Three buttons finish the dialog:

  • More options sets an assembly display name, refName aliases (e.g. to treat chr1 and 1 as the same contig), or cytoband data
  • Add another genome stages the current genome and starts on the next, for loading several at once for comparative views
  • Open (shown as Open N genomes once you've staged more than one) opens a linear genome view on the new assembly, ready for tracks

Using a pre-loaded genome

For a common reference genome, use Show all available genomes, which needs no files. The table is searchable by name, scientific name, or accession, and grouped by source (UCSC main genomes, GenArk, and so on). Star a genome to add it to the Favorite genomes quick-launch list on the start screen.

Launching a public assembly. Show all available genomes (1) opens the table, and launch (2) opens a session on that genome, here T2T CHM13v2.0/hs1 with the assembly's hub tracks listed in the track selector.

The Quickstart list works the same way for genomes you've saved yourself (see Saving a genome to the quickstart list). Check multiple entries and click Go to open them together in one combined session, handy for comparative genomics.

Adding tracks

Once a genome is open, add data tracks from local files or URLs.

Open the File menu and choose Open track..., or open the track selector and use its Add track button. Either opens the "Add a track" form.

Adding a track. File then Open track... (1) opens the form, which takes a main file as a local path or a URL (2) and infers the index from it (3). Confirming the guessed track type adds the track to the open view, the third frame.
  • Choose Add a track from file or URL.
  • Set the Main file (the data file) and optionally an Index file. For formats that need one (BAM/CRAM/tabix), the index URL is inferred from the main file if you leave it blank. You can pick local files or paste URLs.
  • Click Next. JBrowse guesses the Track type and Adapter type from the file; confirm or adjust them, set a Track name, and pick the assembly to add the track to.
  • Click Add.

JBrowse desktop supports the same file formats as JBrowse web. See Supported file types. For the indexing and preparation commands behind these formats, see the web quick start.

To load many tracks at once, choose Add multiple tracks at once in the "Add a track" form.

Gene annotations (GFF3 and GTF)

Both load through the same form, and a plain .gff3 or .gtf needs no index — pick the file and desktop reads it. That is the fast path for one chromosome's worth of annotation.

Sort, bgzip and tabix anything genome-scale before loading it. An unindexed file is parsed once and held whole in memory, so a full annotation costs that much resident before the first feature draws. The commands are in the web quick start under GFF3 and GTF; jbrowse sort-gff handles both formats. Give the form the .gff.gz or .gtf.gz as the main file and it infers the .tbi beside it.

Connecting to a track hub

To pull in a whole set of tracks at once, use File → Open connection... and point it at a UCSC track hub or a JBrowse hub. The connection's tracks then appear in the track selector alongside any you added by hand.

Making tracks searchable by name

To search a track by gene name or feature ID from the location box, index its feature names: open the track's menu (the ⋮ button on the track, or its entry in the track selector) and choose Index track. Indexing runs as a background job; when it finishes, names from that track can be typed straight into the search box. This is the in-app equivalent of the CLI jbrowse text-index command.

Index track only appears on a track it can index — GFF3, GTF and VCF, plain or tabix-indexed.

Saving and reopening sessions

JBrowse desktop autosaves your work continuously, and autosaves show up in "Recently opened sessions" on the start screen.

The File → Session menu handles named sessions:

  • Save session as... writes a .jbrowse file you can reopen later (or share)
  • Open config.json or .jbrowse file... reopens one, as does the start screen's Open .jbrowse or config.json or link menu
  • Export session to web... produces a shareable URL, to hand a session off to someone running JBrowse web

The reverse direction works too, in JBrowse Desktop 5.0 and newer: Open .jbrowse or config.json or link → Open JBrowse Web link... on the start screen, or File → Session → Open JBrowse Web link... once a session is open. Either takes a JBrowse web URL and rebuilds it here as a new session. Two link forms work:

  • one containing a session spec (&session=spec-...) — for example the "Open this view in JBrowse" link under any figure in these docs
  • one using the URL parameter shorthand, i.e. &assembly= with an optional &loc=, &tracks=, &highlight= and so on
  • one naming a track hub with &hubURL=, which is attached as a connection; add &assembly= naming one of the hub's genomes to open at a particular place in it, or leave it off to land at the hub's own default position

The config the link names is downloaded and saved alongside the session, so it reopens later like any other. Share links (&session=share-...) can't be opened this way: only the JBrowse web instance that created one can resolve it.

Figures in these docs also offer an "Open this view in JBrowse Desktop" button, which hands the view straight to Desktop through a jbrowse:// link that the macOS and Windows installers register for you. The Linux AppImage doesn't register anything by itself, so that button generally won't work there unless you've integrated the AppImage with your desktop (e.g. with AppImageLauncher): paste the link instead, or pass it on the command line (below).

Saving a genome to the quickstart list

To turn a session into a reusable quickstart entry, select it in "Recently opened sessions" and choose Add to quickstart list (the playlist-add icon in list view, or the entry's action menu). It then appears in the Quickstart list on the left panel for one-click launching.

Launching from the command line

If you start JBrowse Desktop from a terminal, you can pass a session (.jbrowse) or a configuration (config.json) file to open it straight away, skipping the start screen:

# Linux AppImage
./jbrowse-desktop-*-linux.AppImage myproject/config.json

# Linux (installed) / Windows
jbrowse-desktop mysession.jbrowse

# macOS
open -a "JBrowse 2" myproject/config.json

Relative paths inside a config.json are resolved against that file's own folder, so a config the CLI builds opens with no extra setup.

A jbrowse:// link works as an argument too, which is how to open one on Linux, where the AppImage does not register the URL scheme itself (quote it, so the shell leaves the & alone):

./jbrowse-desktop-*-linux.AppImage 'jbrowse://open?url=https%3A%2F%2Fjbrowse.org%2F...'

Other flags:

jbrowse-desktop --renderer webgl   # force WebGL instead of auto-detecting WebGPU
jbrowse-desktop --renderer canvas  # force the Canvas2D fallback
jbrowse-desktop --version          # print the version and exit
jbrowse-desktop --help             # print usage and exit

--renderer is useful when WebGPU is unavailable or misbehaving, for example running over X11 forwarding or a remote desktop. Use webgl first, and canvas only if WebGL is also unavailable.

See also