Environments

plot() detects where your code is running and opens the Browzarr view in the most convenient place for that environment. You rarely need to do anything — but here is what happens in each context, and how to override it.

How detection works

When you call .plot(), the library checks, in order:

1. give_url=True — skip opening anything; just return the hosted URL string.
2. external_browser=True — always open in your OS default browser.
3. Jupyter / JupyterLab — embed the view as an inline IFrame in the notebook output.
4. VS Code — open the view in VS Code's built-in Simple Browser tab (via the code CLI). Falls back to an external browser if the Simple Browser can't open.
5. Google Colab — serve the local port as an inline iframe via output.serve_kernel_port_as_iframe.
6. Otherwise — open in the OS default browser (with a note printed that the environment wasn't recognized).

Behavior per environment

Jupyter / JupyterLab

The view is rendered inline in the cell output using an IFrame. Size it with width/height:

bz.plot(width=900, height=600)

VS Code

If not using Jupyter within VS Code, plotting opens in the built-in Simple Browser tab, so the view stays inside the editor. This requires the code CLI to be on your PATH (it is, by default, in a VS Code installation). If it can't open, it falls back to the external browser.

Google Colab

Uses the Colab kernel to serve the local port as an inline iframe, so the view appears inside the notebook without opening a new tab.

Plain terminal / script

Opens your OS default web browser at the local server URL.

Controlling where it opens

plot() arguments

# Just get a shareable URL
url = bz.plot(give_url=True)
print(url)

# Always use the OS browser, even in a notebook
bz.plot(external_browser=True)

Local server & ports

• A single local HTTP server is shared across all Browzarr objects in a process. Repeated .plot() calls reuse it rather than spawning duplicates.
• The server binds to localhost and picks the first free port starting at 8765. Browsers treat localhost as a secure context, which WebGPU requires — so no HTTPS or certificate setup is needed.
• To stop the shared server and free its port, call:

from browzarr.api import BrowzarrSession

BrowzarrSession.shutdown()