vibe-view desktop app (macOS, Windows, Linux)

vibe-view ships a native desktop application (an Electron window) in addition to the browser-based viewer. It gives you a real app window with native menus, drag-and-drop, an Open Recent list, and (on macOS) a double-click file association for .qvf files. The same codebase runs on macOS, Windows, and Linux.

Note

The desktop app is a thin native shell around vibe-view’s Python server: it launches vibe-view serve in the background and shows it in a window. So it needs Python and vibe-view installed on the machine (see Prerequisites).

If you launch the app and it can’t find a suitable Python, it no longer fails with a dead-end error; it shows a setup screen that names exactly what is missing (Python, vibe-view, or the [viewer] extra), gives you the command to install it, and lets you install and press recheck to continue in place (see First run below).

The desktop packages are not a self-contained Python bundle: the app is downloaded and, on first run, guides you to install the vibe-view[viewer] Python package. Bundling a full Python + VTK runtime into the installer was evaluated and deferred (see vibe-view/docs/desktop_packaging_design.md).

Prerequisites (all platforms)

Requirement	Version	Notes
Python	3.11 or newer	https://python.org/
vibe-view	current	installed with the [viewer] extra (below)

vibe-view is not on PyPI yet, so it installs from the co-located checkout.

Install

The steps are the same on all three platforms. From a vibe-qc checkout:

# uv (vibe-qc's stated installer): vibe-qc + vibe-view in one step
uv pip install -e '.[viewer-gpu]'

# or with pip, in two steps (pip does not read [tool.uv.sources]):
pip install -e .
pip install -e 'vibe-view/[viewer]'

The [viewer] extra is required for the desktop app: it pulls the interactive server stack (trame, uvicorn). Installing vibe-view without it gives the lean headless-capture stack only, and the desktop window will report that the server did not start.

Verify:

vibe-view --version
# vibe-view 2.1.0.dev0  -- Roothaan's Roadrunner

Launch

vibe-view desktop                 # native window, browse page for the cwd
vibe-view desktop water.qvf       # native window with water.qvf loaded
vibe-view desktop --port 9090     # custom server port

vibe-view desktop works from any directory. On first run it downloads the Electron binary (about 120 MB, one time) and brands it as vibe-view. It then records the interpreter it ran from, so a later double-click on a .qvf file (macOS) reuses the same virtualenv.

First run: setup screen

When the app starts it looks for a Python that can run the viewer server. If it can’t find one (a freshly downloaded app on a machine with no vibe-view, or a Python that has vibe-view but not the [viewer] extra), it opens a setup screen instead of failing. The screen tells you which of three cases applies and shows a command to fix it.

The command installs vibe-view into a dedicated virtualenv rather than into the system Python:

# macOS / Linux (the screen fills in the real path):
python3 -m venv ~/.local/share/vibe-view/venv
~/.local/share/vibe-view/venv/bin/pip install "vibeview[viewer]"

```{admonition} Why a virtualenv, not a plain pip install? :class: important On Homebrew Python (macOS) and Debian / Ubuntu / Fedora system Pythons, a plain pip install "vibeview[viewer]" fails with error: externally-managed-environment (PEP 668): those interpreters are marked off-limits to pip. A fresh virtualenv is never externally managed, so installing into one sidesteps the error entirely. The app looks for this venv at $XDG_DATA_HOME/vibe-view/venv (default ~/.local/share/vibe-view/venv; %LOCALAPPDATA%\vibe-view\venv on Windows), so Recheck finds it automatically with no extra step. If you prefer, pipx install "vibeview[viewer]" (then run vibe-view desktop once to register it) works too; installing into the system Python with --break-system-packages is possible but discouraged.

Copy the command with the **Copy** button, run it in a terminal, then press
the **recheck** button. The app re-scans and, once it finds a capable
interpreter, starts the server and opens the viewer, with no restart needed.
The app stays open the whole time, so you can fix the environment without
losing your place.

```{note}
Until vibe-view is published to PyPI, `pip install "vibeview[viewer]"`
resolves only if pip can reach the package: from a vibe-qc **checkout**,
install the local path into the venv instead:
`~/.local/share/vibe-view/venv/bin/pip install -e 'vibe-view/[viewer]'` (run
from the checkout root). The venv is still what avoids the PEP 668 error; only
the package source differs. Launching with `vibe-view desktop` from any
vibe-view environment also records that interpreter, so the setup screen is
skipped on later runs.

macOS: double-click a .qvf

Two ways to open files:

1. vibe-view desktop <file> works immediately after install, no app bundle needed.

2. Double-click a .qvf (Finder file association) needs the packaged .app. Build it once from the checkout:

   cd vibe-view/electron
   ./build-desktop.sh          # produces dist/mac-arm64/vibe-view.app + a .dmg
   

   Then run vibe-view desktop once from your virtualenv so the app knows which Python to use. After that, double-clicking a .qvf opens it in the app.

Note

The current .app / .dmg is not code-signed, so on first launch macOS Gatekeeper may block it. Right-click the app and choose Open (once) to allow it. Signing and notarization are part of the downloadable packages roadmap item.

Windows and Linux

vibe-view desktop is the supported launch path on Windows and Linux too, with the same prerequisites (Python plus vibe-view[viewer]). electron-builder targets exist for Windows (nsis installer) and Linux (AppImage); like the macOS app they rely on a Python environment being present, and the first-run setup screen guides the user to install it.

On Windows the app looks for the py launcher and python (in that order) rather than python3, which Windows usually doesn’t provide; a virtualenv is found at .venv\Scripts\python.exe.

Warning

Windows is supported but not yet verified, and we want your feedback. The maintainers develop and test on macOS and Linux and have no Windows machine, so the Windows build is shipped untested: the nsis installer, the py-launcher Python discovery, and the setup screen have not been run on real Windows. The app says as much in a one-time notice on its first Windows launch. Please tell us how it goes, whether it works or breaks, by opening an issue; that feedback is what will make Windows a first-class target. The Windows installer is also not code-signed, so SmartScreen warns on first run: choose More info, then Run anyway. Code signing is a pending infrastructure item (shared with the macOS Gatekeeper gate above).

Troubleshooting

The setup screen keeps appearing after I installed vibe-view. The app scans a fixed set of interpreters (python3, python, python3.13 … on macOS/Linux; py, python on Windows) plus the interpreter recorded by a previous vibe-view desktop run. If you installed vibe-view[viewer] into a virtualenv that isn’t on that list, the app won’t find it from a bare double-click. Run vibe-view desktop once from that environment; it records the interpreter (in <XDG_CACHE_HOME>/vibe-view/interpreter.json) so future launches and double-clicks reuse it. Confirm the environment is capable with:

python -c "import vibeview, trame, uvicorn; print('ok')"

“The vibe-view server did not start.” Older builds showed this error and quit; current builds route the same conditions to the setup screen instead, which names what’s missing and lets you fix it in place.

“Check for Updates”. In a packaged app (built with build-desktop.sh or installed from a .dmg), this checks the update feed at https://vibe-qc.com/updates/vibe-view/ and tells you when a newer version is available. Because the current macOS build is not code-signed, it cannot install updates by itself: instead of a “Restart to install” prompt you get a Download button that opens the new .dmg, and you update by replacing the app. Full hands-off self-install turns on automatically once a signed + notarized build ships (see the Gatekeeper note above). When you launch vibe-view desktop from a source checkout (not a packaged app), automatic updates are unavailable: update with git pull and rebuild. Feed, signing, and publishing details are in vibe-view/electron/PUBLISHING.md.

See also

• vibe-view interactive viewer (the browser-based viewer and the full section-by-section reference)

• vibe-view/electron/PUBLISHING.md (building, the update feed, and the code-signing gate for auto-update)

• vibe-view/electron/README.md (developer notes for the desktop app)