Skip to main content

Installing plugins

Plugins add track types, view types, data adapters and menu items, and some bring their own data. How you install one, and how long it stays, depends on where you run JBrowse.

The full catalog, each plugin with its config snippet, is on the plugin store page. To write your own plugin, see the developer guide.

Where are you running JBrowse?

Is it already loaded?

A hosted config often loads the plugins its tutorials need. Open Tools → Plugin store; Installed plugins at the top lists what this session loaded.

Tools then Plugin store opens the store. Installed plugins lists what is loaded now.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

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%7D%5D%7D&sessionName=JBrowse+docs%3A+plugin_store

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.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-20000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/volvox/config.json, which is what the Web button above opens.

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-20000"
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-20000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

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

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

The figure was taken after clicks this command does not make, so its picture can differ.

It leaves out 3 callouts anchored to what the clicks bring up.

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.

If the plugin is listed there, there is nothing to install; if not, install it.

The plugin store

Open Tools → Plugin store, type the plugin's name into Filter plugins and click Install. JBrowse reloads with the plugin and keeps your views.

The plugin store filtered to one plugin, with its Install button.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

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%7D%5D%7D&sessionName=JBrowse+docs%3A+plugin_store_install

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.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-20000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/volvox/config.json, which is what the Web button above opens.

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-20000"
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-20000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

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

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

The figure's clicks open the plugin store, filtered to MsaView; this command draws the view under it.

It leaves out the callout anchored to what the clicks bring up.

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.

Some plugins (e.g. CIVIC) add their data when installed. Others register a new track type or adapter, which needs a matching track config before it draws anything.

How long it lasts: this session. A share link includes the plugin, but a new session starts without it. For every visit, keep it.

Not in the store? Load it by URL.

Keeping a plugin for every visit

Click the pin beside a plugin in Installed plugins, and JBrowse loads it every time you open this config in this browser.

A store plugin in the Installed plugins list, with the pin that keeps it for every visit.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

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%7D%5D%7D&sessionName=JBrowse+docs%3A+plugin_store_keep

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.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-20000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/volvox/config.json, which is what the Web button above opens.

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-20000"
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-20000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

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

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

The figure's clicks install MsaView from the plugin store, which this command does not do, so its picture differs there.

It leaves out the callout anchored to what the clicks bring up.

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.

  • The list is per configuration, not per site. A plugin kept on jbrowse.org/code/jb2/main/?config=demos/hg002/config.json does not load on another demo, or on another version of the app.
  • JBrowse stores the list in this browser, so a session you share, or the same JBrowse opened on another machine, starts without these plugins.
  • A kept plugin that did not load this visit (switched off, or skipped after a crash) is still a row in Installed plugins, with a switch beside it.
  • On the admin server the store writes to config.json for every visitor instead, so the pin does not appear there.

JBrowse loads kept plugins before it draws anything, so a plugin that crashes on load would crash the app on every visit. To recover:

  • The fatal error dialog offers Reload without permanent plugins.
  • If a load never finishes, JBrowse turns the stuck plugins off before the next visit. The plugin store then shows a banner naming them, with a switch per plugin and a Turn back on and reload button once the culprit is switched off.

Adding ?safeMode to the URL skips every kept plugin for one load.

JBrowse Desktop

Desktop has two routes:

  • Tools → Plugin store inside a session works as in JBrowse Web. How long it lasts: as long as that session file; other sessions don't load it.
  • Global plugins..., in the start screen's menu, installs a plugin for every session on this machine, from the next session you open.
Global plugins from the start screen menu (1) opens the dialog, whose Add custom plugin (2) takes a UMD build's name and URL (3) or, under Advanced options, an ESM build's URL (4).

The dialog lists the store's plugins under Available plugins, each with an Install button. If a plugin crashes on load, switch it off there to keep it installed, or remove it. Reload without global plugins, in the same start-screen menu, skips the whole list for one launch.

Not in the store? Load it by URL.

A plugin that isn't in the store

Beta plugins often load by URL before they reach the store, and their tutorials give the URL. Where you enter it depends on where you run JBrowse:

  • JBrowse Desktop: Add custom plugin, in the Global plugins dialog for every session, or in a session's plugin store for that session.
  • The admin server: Add custom plugin in the plugin store, which writes it to config.json.
  • JBrowse Web, as a visitor: there is no button. Ask the site's admin to add it to config.json, or open a session link whose sessionPlugins names it.

The Add custom plugin form asks for different fields for each build:

  • a UMD build (a .umd.js file): Plugin name and Plugin URL
  • an ESM build: open Advanced options, paste the URL into ESM build URL, and leave the rest empty

In config.json

The top-level plugins array in config.json loads a plugin for everyone who opens that config. A store plugin goes in by its store name (storePlugin) and any other by its URL; Plugins has the fields. The jbrowse CLI has no plugin command, so edit the file by hand, or install from the plugin store on the admin server, which writes the entry for you.

How long it lasts: until someone removes the entry.

Embedded components

An embedded component takes its plugins as a prop; see Embedded components and the inline plugins example.

How long each install lasts

Where you install itLasts
Web plugin storethis session, and is included in its share link
Web plugin store, keptevery visit to this config, in this browser only
Web plugin store on the admin serverwritten to config.json, for every visitor
Desktop plugin storethe open session file
Desktop Global plugins...every session on this machine
config.jsonevery visitor to that config

See also