Let's get biopb running.

Answer a question or two below and you'll get the exact steps for your machine. For most people it's a single copy-paste — with a little extra setup on Windows.

Before you start: make a note of where your image data lives — the folder or drive your microscopy files are in. Partway through, the installer asks for that location in a plain text terminal, so it's smoother if you already have the path handy. Not sure yet? No worries — you can point biopb at your data later too.

First things first — what kind of computer are you on?

You're one command away. 🎉

  1. Install biopb

    Open your Terminal — on Mac, press ⌘ + Space, type “Terminal”, and hit Enter; on Linux you already know where it lives 😉 — then paste this in and press Enter:

    Terminal — Mac / Linux
    $ curl -fsSL https://biopb.org/install.sh | bash

    Let it run. It downloads biopb, sets up its data server, and installs a friendly AI agent (OpenCode). Partway through it'll pause to help you set up a free OpenCode Zen account — just follow the prompt (no credit card, free models included) and paste the key back when it asks. After that you're wired up.

    Never pasted a command like this before? Totally normal. curl … | bash just means “download our little setup script and run it.” Want to read exactly what it does first? It's plain text at biopb.org/install.sh.

  2. Open your agent and ask ✨

    That's it — no server to start. Open your AI agent — Claude Code, OpenCode, or Cursor — and just ask it to open an image or run an analysis. Your agent launches biopb on its own whenever it needs it. That's the whole workflow.

Windows: one quick extra step. 🪟

BioPB supports several popular agent interfaces (the chat window). It's best to install one of these first, so BioPB knows which one to wire up.

Quick check — do you already use one of these agents?
OpenCode, Claude Code, Claude Desktop, or Cursor

  1. Run the installer

    Open PowerShell (the normal one — no administrator needed), then paste:

    PowerShell
    > powershell -c "irm https://biopb.org/install.ps1 | iex"

    It finds your agent — OpenCode, Claude Code, Claude Desktop, or Cursor — and connects biopb to it automatically. Nothing to configure by hand.

  2. Open your agent and ask ✨

    No server to start — open your agent and ask it to load an image or run an analysis. Your agent launches biopb on its own whenever it needs it.

  1. Install the OpenCode desktop app

    Download OpenCode for Windows from opencode.ai/download and run the Windows installer (next-next-finish). This is the free chat app you'll talk to biopb through.

    On first launch it'll ask you to connect an AI model. Choose OpenCode Zen and create a free account — no credit card needed, and it comes with a few free models to get you started. (Already have an Anthropic or OpenAI key? You can paste that in instead.)

  2. Run the installer

    Open PowerShell (the normal one — no administrator needed), then paste:

    PowerShell
    > powershell -c "irm https://biopb.org/install.ps1 | iex"

    It finds your OpenCode app and connects biopb to it automatically — nothing to configure by hand.

  3. Open OpenCode and ask ✨

    No server to start — open OpenCode and ask it to load an image or run an analysis. OpenCode launches biopb on its own whenever it needs it.

Curious what that command does? irm … | iex is just PowerShell for “download our setup script and run it.” You can read it first at biopb.org/install.ps1.

Troubleshooting 🔧

Hit one of these? Here's the quick fix. Rerunning is always safe — the installer is idempotent, so it just picks up where it left off.

Windows: “running scripts is disabled on this system”

Windows blocks PowerShell scripts by default. The simplest fix is to run the installer with a one-time bypass — paste this into PowerShell (the normal one, no administrator needed):

PowerShell
> powershell -ExecutionPolicy Bypass -c "irm https://biopb.org/install.ps1 | iex"

Prefer to fix it for good? Allow signed scripts for your account once, then rerun the normal one-liner:

PowerShell
> Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
On a work or school PC, a company Group Policy can override both of these. If scripts are still blocked, ask your IT admin to allow them.
Windows: “tar not found”, or it tells you to update Windows

The installer relies on tar, which ships with Windows 10 version 1803 and newer. If you see this, your Windows is too old. Check your version by pressing ⊞ Win, typing winver, and hitting Enter — then update to Windows 10 (1803+) or Windows 11 and rerun.

macOS: the install stalls compiling llvmlite, or won't finish

You're most likely on an older macOS than the prebuilt wheels support. biopb needs macOS 12 Monterey or newer on Apple Silicon (arm64), or macOS 10.15 Catalina or newer on Intel (x86_64).

napari's optional numba accelerator pulls in llvmlite, whose prebuilt wheels target those OS floors. On an older macOS there's no matching wheel, so the installer falls back to compiling llvmlite from source — which needs an LLVM toolchain and fails on a stock machine. Upgrading macOS is the fix; there's no build workaround the installer can apply for you.

“Unsupported OS” or “Unsupported architecture”

biopb installs on Linux, macOS, and Windows, running on 64-bit Intel/AMD (x86_64) or ARM (arm64, including Apple Silicon). Older 32-bit machines aren't supported.

Linux: “curl: command not found”

Some minimal Linux images don't ship curl. Install it first, then rerun the one-liner (on Debian/Ubuntu):

Terminal
$ sudo apt update && sudo apt install -y curl
It installed, but biopb or my agent “isn't recognized”

The installer adds biopb to your PATH, but a terminal that was already open won't see the change. Close that window, open a fresh one, and try again. If it still can't be found, just rerun the installer — it's safe to run twice and will finish wiring everything up.

Still stuck? We've got you. 🤝

Hit a snag or an error you don't recognize? Open an issue on GitHub (paste the message you saw), or ask the friendly bioimaging crowd on the image.sc forum. No question is too basic.