JBrowse web quick start

This guide sets up a self-hosted JBrowse web instance: you'll use the @jbrowse/cli command-line tool to download JBrowse, add an assembly and tracks, and serve the result as a folder of files on a web server.

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 config.json directory you build in this guide opens directly in JBrowse Desktop as well. See JBrowse CLI with Desktop.

TLDR#

• Install Node.js 18+, samtools, tabix
• 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 .

Reproduce it end to end#

The TLDR above uses placeholder filenames (genome.fa, file.bam, file.vcf) that you supply. build_quickstart_web.sh runs the same flow against the volvox sample data JBrowse ships:

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 downloads a FASTA, a BAM, a BigWig, a VCF, and a GFF3, runs the same samtools faidx / samtools index / bgzip + tabix indexing and add-assembly / add-track / text-index commands, and writes a config.json with an alignments track, a coverage track, a variant track, and a searchable gene track. Every input is pinned, so re-running reproduces the same config. It needs samtools, htslib's bgzip and tabix, curl, and node (for the JBrowse CLI).

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

This downloads and unzips jbrowse-web into a folder named jbrowse2. Run cd jbrowse2 before any further commands. Alternatively, download the zip manually from https://github.com/GMOD/jbrowse-components/releases.

Running JBrowse 2#

JBrowse 2 requires a web server. Opening index.html directly in your browser won't work.

To verify locally:

cd jbrowse2/
npx serve -S .

The -S flag tells serve to resolve symlinks, relevant if you later add tracks with --load symlink.

Navigate to http://localhost:3000. Click the sample config to confirm the install works.

For production, place the folder in 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#

The examples below run from inside jbrowse2/, so they omit --out (which defaults to the current directory). To write elsewhere, add --out /var/www/html/jbrowse2, either a directory containing config.json or a path to a specific config file. Run jbrowse add-track --help for all options.

For the full list of supported formats and the adapter each maps to, see Supported file types.

Every example below uses --load copy, which puts the data file next to config.json so one server serves both. For data your lab already hosts somewhere else, pass the URL in place of a path and the track records that URL; see the hosting section below.

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

Genome assembly (FASTA)#

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

This writes an assembly entry to config.json and copies genome.fa and genome.fa.fai into the output directory. Use --load symlink to symlink instead of copying.

Use --name (shorthand -n) to set a human-readable assembly name (defaults to the filename).

JBrowse 2 also supports bgzip-compressed indexed FASTA and 2bit files.

✕

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 file.vcf
tabix file.vcf.gz
jbrowse add-track file.vcf.gz --load copy

If tabix reports the VCF is unsorted, sort it first:

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

See https://www.htslib.org/ for more on bgzip, tabix, and bcftools.

✕

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#

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#

GTF shares GFF3's refname and start columns, so sort-gff sorts it 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 any of this, but the whole file is read at once, so sort and index anything genome-scale.

GTF has no Name or ID attribute, so transcripts are grouped 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 — alongside its GFF3 defaults, so searching by gene name works on a GTF track without passing --attributes.

See the gene track guide.

Synteny (PAF)#

Use minimap2 to align two assemblies 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

Note: --assemblyNames takes query,target, the reverse of minimap2's target query order. Above, minimap2 grape.fa peach.fa makes peach the query, so load with --assemblyNames peach,grape:

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

Setting the named queryAssembly and targetAssembly fields on the adapter in config.json avoids the ordering question (see the synteny track config guide).

Pick the -cx preset by how far apart the two assemblies are:

• asm5 - closely related assemblies, up to ~5% divergence
• asm10 - moderately diverged assemblies
• asm20 - divergent / cross-species comparisons, up to ~20% divergence, used above

See the minimap2 docs for details.

Other supported synteny formats:

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

Add them the same way: jbrowse add-track alignment.delta --assemblyNames query,target .... 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 just built is a static site: plain files that a web server hands out unchanged, with no server-side program or database. All the work happens in the visitor's browser, which fetches the pieces of your data files it needs.

Any web server, S3 or GCS bucket, or institutional file host can serve it. See Deploying JBrowse Web for the full picture, including generating config.json from a samplesheet.

Two properties decide whether a host works, and both fail quietly:

• Byte-range requests. JBrowse reads slices of a BAM, CRAM, BigWig, or tabix file rather than downloading it, so the host has to answer a Range header with 206 Partial Content. A host that returns the whole file with 200 instead is the usual reason a track that works locally shows nothing in production. See Serving data files.
• No re-compression of compressed files. Serving a .bam or .bgz through gzip corrupts the byte offsets the index depends on. See Serving data files.

Object storage satisfies both out of the box, which is why S3 and GCS are common homes for the data even when the app itself is served elsewhere. Data on a different domain than the app needs a CORS policy as well.

For data that cannot be public, JBrowse authenticates per file host. See Authentication.

Indexing feature names for searching#

Optionally, build a text index so users can search by gene name or feature ID:

jbrowse text-index

This indexes the GFF3, GTF and VCF tracks in your config, tabix-indexed or plain. Every other track is skipped, and a bare text-index run skips silently — name a track with --tracks and it says why that one was left out. Once complete, names can be typed directly into the location search box. See Text searching for which attributes are indexed and how to narrow the set, the text-index docs for the 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