JBrowse web quick start

Install the @jbrowse/cli, download JBrowse web, add an assembly and tracks, and serve the result as a folder of static files.

Other ways to run JBrowse:

• JBrowse desktop - open local files without a web server
• Embedded components - embed a view in your own web app

The folder this guide builds also opens directly in JBrowse Desktop. See JBrowse CLI with Desktop.

TLDR#

Needs Node.js 18+, samtools and tabix. Swap genome.fa, file.bam and file.vcf for your own files.

npm install -g @jbrowse/cli
jbrowse create jbrowse2 && cd jbrowse2

samtools faidx genome.fa
jbrowse add-assembly genome.fa --load copy

samtools index file.bam
jbrowse add-track file.bam --load copy

bgzip file.vcf
tabix file.vcf.gz
jbrowse add-track file.vcf.gz --load copy

jbrowse text-index
npx serve -S .

Each add-* command writes an entry to config.json and copies the data file next to it. The result is a static site: no database, no server-side code.

Reproduce it end to end#

build_quickstart_web.sh runs the same flow against the volvox sample data JBrowse ships, with every input pinned:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_quickstart_web.sh
bash build_quickstart_web.sh               # builds ./quickstart_web_build/jbrowse2
npx serve -S quickstart_web_build/jbrowse2 # then open the printed URL

It needs samtools, bgzip, tabix, curl and node, and produces a config with an alignments track, a coverage track, a variant track and a searchable gene track.

Prerequisites#

• Node.js 18+ - use NodeSource or NVM, not apt (tends to install old versions)
• samtools: sudo apt install samtools or brew install samtools
• tabix: sudo apt install tabix or brew install htslib
• bcftools (optional, for VCF sorting/indexing): sudo apt install bcftools or brew install bcftools

Installing the JBrowse CLI#

npm install -g @jbrowse/cli
jbrowse --version

To avoid a global install, replace jbrowse with npx @jbrowse/cli in any command below.

Download JBrowse 2#

jbrowse create jbrowse2
cd jbrowse2

This downloads and unzips jbrowse-web into jbrowse2/. The rest of this guide runs from inside that folder. The zip is also available from https://github.com/GMOD/jbrowse-components/releases.

Running JBrowse 2#

JBrowse 2 needs a web server; opening index.html directly does not work.

npx serve -S .

-S resolves symlinks, which matters once you add tracks with --load symlink. Open http://localhost:3000 and click a sample config to confirm the install.

For production, copy the folder into your web server's static directory (e.g. /var/www/html/jbrowse2/) and visit http://yourserver/jbrowse2.

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-50000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%5D%7D&sessionName=JBrowse+docs%3A+sample_config

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-50000",
)

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Adding tracks#

Every command below:

• runs from inside jbrowse2/, so --out is omitted. Pass --out /var/www/html/jbrowse2 (a directory holding config.json, or a config file path) to write elsewhere
• uses --load copy, which puts the data file next to config.json. Use --load symlink to symlink instead

For data already hosted elsewhere, pass the URL instead of a path and the track records that URL:

jbrowse add-track https://data.myuniversity.edu/rnaseq/sample1.bam

Most formats need an index file (.fai, .bai, .tbi) beside the data file. JBrowse never downloads a whole BAM or VCF; the index tells it which byte range holds the region on screen. add-track finds the index by its conventional name and records both.

jbrowse add-track --help lists all options. Supported formats and the adapter each maps to: Supported file types.

Genome assembly (FASTA)#

samtools faidx genome.fa
jbrowse add-assembly genome.fa --load copy

--name (-n) sets the assembly name, which defaults to the filename. Bgzip-compressed indexed FASTA and 2bit also work.

✕

Do it yourselfIn DesktopSession specWith an agent

The steps behind the figure above, run against your own data.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+lgv_assembly

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": []
}

Loaded against config: test_data/volvox/config.json

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

BAM / CRAM#

samtools index file.bam   # or file.cram
jbrowse add-track file.bam --load copy

See the alignments track guide.

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a CRAM file (.cram + .crai).This figure uses “volvox-sorted.cram (contigA, default display)”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-20000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-20000%22%2C%22tracks%22%3A%5B%22volvox_cram_alignments%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+volvox_alignments

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_cram_alignments"
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-20000",
)

view.add_track({
    "type": "AlignmentsTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "CramAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_cram_alignments"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

VCF#

VCFs must be bgzip-compressed and tabix-indexed. bgzip is gzip written in blocks, so tabix can jump to a region without decompressing the whole file; a plain gzip file cannot be indexed:

bgzip file.vcf
tabix file.vcf.gz
jbrowse add-track file.vcf.gz --load copy

If tabix reports the VCF is unsorted:

bcftools sort file.vcf > file.sorted.vcf
bgzip file.sorted.vcf
tabix file.sorted.vcf.gz

✕

Do it yourselfIn DesktopSession specIn a notebookWith an agent

The steps behind the figure above, run against your own data.

1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “volvox 1000genomes vcf”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:5000-10000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A5000-10000%22%2C%22tracks%22%3A%5B%22volvox_test_vcf%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+volvox_variants

This session spec pastes after &session=spec- on any JBrowse Web instance.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:5000-10000",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

Copy

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:5000-10000",
)

view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:5000-10000",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

For multi-sample VCFs, see the multi-sample variant guide.

BigWig / BigBed#

No external index needed:

jbrowse add-track file.bw --load copy

See the quantitative track guide.

GFF3#

GFF3 is often unsorted, and tabix needs features ordered by reference name and start, so sort before compressing:

jbrowse sort-gff yourfile.gff | bgzip > yourfile.sorted.gff.gz
tabix yourfile.sorted.gff.gz
jbrowse add-track yourfile.sorted.gff.gz --load copy

See the gene track guide.

GTF#

sort-gff sorts GTF too:

jbrowse sort-gff yourfile.gtf | bgzip > yourfile.sorted.gtf.gz
tabix yourfile.sorted.gtf.gz
jbrowse add-track yourfile.sorted.gtf.gz --load copy

A plain .gtf loads without indexing, but is read whole, so sort and index anything genome-scale.

GTF has no Name or ID attribute. Transcripts group into a gene by gene_id, and aggregateField names the attribute that labels the gene. jbrowse text-index matches the GTF spellings (gene_name, transcript_name, gene_id, transcript_id) without --attributes.

See the gene track guide.

Synteny (PAF)#

Align two assemblies with minimap2 and load the result as a synteny track:

minimap2 -cx asm20 grape.fa peach.fa > peach_vs_grape.paf

jbrowse add-assembly grape.fa --load copy -n grape
jbrowse add-assembly peach.fa --load copy -n peach
jbrowse add-track peach_vs_grape.paf --assemblyNames peach,grape --load copy

--assemblyNames takes query,target, the reverse of minimap2's target query argument order. Setting queryAssembly and targetAssembly on the adapter in config.json avoids the question (see the synteny track config guide).

Pick the -cx preset by divergence:

• asm5 - closely related, up to ~5% divergence
• asm10 - moderately diverged
• asm20 - cross-species, up to ~20% divergence

Other synteny formats load the same way (jbrowse add-track alignment.delta --assemblyNames query,target ...):

• .delta (MUMmer/NUCmer)
• .chain (UCSC)
• .anchors and .anchors.simple (MCScan)
• .out (MashMap)

For large alignments, convert to indexed PIF first with jbrowse make-pif.

See also the linear synteny view, dotplot view, synteny visualization tutorial, all-vs-all synteny, and multi-way synteny.

Hosting your own data#

The folder you built is a static site. Any web server, S3 or GCS bucket, or institutional file host can serve it; the browser fetches the slices of each data file it needs. See Deploying JBrowse Web, including generating config.json from a samplesheet.

Two host properties decide whether tracks load, and both fail quietly:

• Byte-range requests. The host must answer a Range header with 206 Partial Content. A host that returns the whole file with 200 is the usual reason a track that works locally shows nothing in production. See Serving data files.
• No re-compression. Serving a .bam or .bgz through gzip corrupts the byte offsets the index depends on. See Serving data files.

Object storage satisfies both by default. Data on a different domain than the app also needs a CORS policy. For data that cannot be public, see Authentication.

Indexing feature names for searching#

jbrowse text-index

This builds a name index, separate from the tabix index, over the feature names and IDs in GFF3, GTF and VCF tracks. Once built, a gene name typed into the location search box jumps to that feature. Other track types are skipped silently; name one with --tracks and it says why. See Text searching for which attributes are indexed, the text-index docs for flags, and the trix index format for how the index files work.

Tutorials#

• JBrowse CLI with Desktop
• Synteny visualization
• Cancer structural variants
• Selection scans (Drosophila DGRP)
• Long-read methylation
• RNA-seq
• All tutorials

See also#

• User guide
• Supported file types
• Config guide
• CLI reference
• FAQ
• CORS errors

Tips#

Organize data into subdirectories:

jbrowse add-track myfile.bam --subDir my_bams --load copy --out /var/www/html/jbrowse2

Upgrade JBrowse to the latest release:

jbrowse upgrade /var/www/html/jbrowse2

Upgrade the CLI:

npm install -g @jbrowse/cli

Use a custom config filename:

jbrowse add-assembly mygenome.fa --out /path/to/jbrowse2/alt_config.json --load copy
# Access at: http://localhost/jbrowse2/?config=alt_config.json