Installation¶

Note

These commands use vibe-view, the launcher available in current published archives and GitHub snapshots. It remains supported in rename-aware builds. Use vibe-viewer only when your installed build includes that launcher; see names and compatibility for substitutions in other examples.

Choose an installation route¶

The self-contained Apple Silicon desktop package includes Python and the viewer runtime and requires macOS 14 or newer. It needs no separate Python, pip, Homebrew or Node.js installation for normal viewing, editing or image capture. See the desktop app for package status and limitations; a source tag does not imply a signed public installer is available.

The following prerequisites and commands apply to source installations and external-runtime desktop shells.

On a cluster login node or another machine without a display, install from source into your home directory and choose the extras for what you will do there; Clusters and remote machines walks through it, together with the vq queue for machines with no batch system, SLURM and PBS/Torque.

What you need for a source installation¶

Python 3.12 or newer. Debian and Ubuntu also need the matching python3-venv package.
Git, to clone the repository.

That is the whole list. There is no Docker image, no C++ compiler, and no native dependency build — vibe-viewer is pure Python plus wheels. In particular it does not build or install vibe-qc.

Note

There is no pip install vibeview yet. The private package index at https://vibe-qc.com/pypi/simple/ is planned but not published, so neither pip install vibeview nor pipx install vibeview resolves today. Install from the checkout, as below.

The public GitHub source can be cloned without credentials. Canonical development access is provided separately to authorized contributors.

Install from a checkout¶

Clone the public source repository:

git clone https://github.com/vibyverse/vibe-viewer.git

Enter the standalone repository and install:

cd vibe-viewer
./scripts/install.sh
source .venv/bin/activate

GitLab remains the canonical development service. Maintainers provide its connection details separately to authorized contributors. Public snapshots can lag development; check the available public tags when selecting a release.

install.sh is for macOS and Linux. It creates a dedicated environment under .venv at the repository root and installs the CLI, the browser viewer, the source-checkout desktop command and the terminal viewer. Electron downloads itself the first time you run vibe-view desktop; pass --with-electron to fetch it during installation instead.

Run every lifecycle script as your regular login user, without sudo, so the checkout, the environment and the Electron runtime keep one consistent owner.

Check the result:

vibe-view doctor

doctor reports the core install and every optional mode, tells you what is missing, and prints the exact command that would fix it. --json makes it machine-readable.

Source archives and downloads¶

Use the standalone viewer’s public tags to select a source snapshot. Extract it, enter the extracted repository root, and run the same ./scripts/install.sh command. A source archive has no Git metadata, so use a clone for update.sh branch switching and pulls.

Validated wheel and source-distribution artifacts are retained by the canonical CI service for the selected revision. Authorized contributors can obtain them from the release owner. Extract the reviewed artifacts and install the wheel in a dedicated environment:

python3 -m venv .venv-viewer
source .venv-viewer/bin/activate
python -m pip install './dist/vibeview-X.Y.Z-py3-none-any.whl[viewer,tui]'

Replace X.Y.Z with the version in the downloaded filename. The Python wheel does not contain the source-backed Electron app; use a checkout for desktop. Repository and CI artifact access may require authentication.

Website wheels belong under https://vibyverse.com/vibe-viewer/docs/_static/downloads/, matching the viewer’s own docs/_static/downloads/ staging directory. As checked on 2026-09-15, the v2.17.1 website wheel is not published there. Do not treat a constructed versioned URL as a download that already exists: use the source install or validated CI artifact until that release’s wheel has been published. The old producer-hosted 2.15.2 wheel is historical, not the current viewer.

Installation profiles¶

install.sh, update.sh and reinstall.sh all take --extras:

Profile	Installs	Use when
`core`	Reading, conversion, headless capture and export	A compute node or CI runner that only produces figures
`viewer`	`core` + the trame/uvicorn browser stack	You want `open` / `serve` / `dashboard`
`tui`	`core` + Textual	You want the interactive terminal viewer
`modes`	The default: viewer + tui + desktop	An ordinary workstation
`all`	Everything installable	You do not want to think about it

Electron and the desktop options need modes, viewer, all or test; core and tui are non-desktop profiles. update and reinstall default back to modes, so repeat --extras if you are maintaining a narrower one.

Optional extras¶

Installing from a wheel or with pip install -e . instead? The extras are what pull in each capability. All of them are optional, and the core install is deliberately lean so a capture-only host does not drag in a web server.

Extra	Pulls in	Unlocks
`viewer`	trame, trame-vtk, trame-vuetify, uvicorn	`vibe-view open`, `serve`, `dashboard`, `desktop`
`tui`	textual	`vibe-view tui` (`vibe-view show` is core)
`ase`	ase	The long tail of structure formats, via `ase.io.read`
`results`	cclib	Common quantum-chemistry output structures and available properties
`biomolecule`	gemmi (MPL-2.0)	PDBx/mmCIF, models and alternate conformers; see biomolecules
`surfaces`	scipy	Molecular VdW/SAS/SES surfaces and numerical morphology
`trexio`	TREXIO	Gaussian wavefunctions and structures from supported TREXIO datasets
`smiles`	rdkit	Build a 3-D structure from a SMILES string
`jupyter`	ipython, ipywidgets	The `%vibeview` notebook magic
`sysinfo`	psutil	CPU and RAM use in the browser viewer’s About dialog
`capture`	nothing	Headless capture and export are core; the name documents a capture-only install
`povray`	nothing	The POV-Ray scene export is core; POV-Ray itself is a separate program
`blender`	nothing	The Blender script export is core; Blender itself is a separate program
`validation`	qvf-writer reference validator	Strict QVF validation; install the pinned qvf release package first (see QVF validation)
`queue`	vibe-scheduler (imports as `vq`)	The vq job panel and `vibe-view from-vq` — see Queue integration
`xtb`	Optional molecular xTB producer via `qvf-writer>=0.7.0rc1`; install the current qvf/python producer source first. Excluded from `all` until the required producer is released. The external xTB executable is separate.
`sketch`	vibesketch	Sketch a molecule in vibe-sketcher from the Build molecule dialog — see Building and editing
`all`	viewer + tui + ase + results + biomolecule + trexio + smiles + jupyter + sysinfo + surfaces	Everything except `queue`, `sketch` and `validation`

These extras have additional setup requirements:

queue is deliberately not in all. vibe-scheduler is published on no package index, so a pip install vibeview[all] that tried to pull it would fail to resolve for everyone. Install vibe-scheduler from its own checkout first; python -m pip install -e '.[queue]' from the viewer root is then satisfied by what is already there. Queue integration has the full story.
sketch is not in all either, for the same reason: vibe-sketcher is published on no index yet. Install it from a vibe-sketcher checkout, then python -m pip install -e '.[sketch]'.
validation needs qvf’s reference package from the pinned release. It is not included in all. Follow strict validation before using vibe-view validate or the Python validate() API. Normal viewing does not require it.
ase is large. vibe-viewer hand-rolls the common formats — XYZ, CIF, PDB, Mol2, GRO, SDF, Cube, Gaussian input — and defers only the long tail to ASE. Most users never need it. vibe-view formats lists what your installation can actually read.

Windows¶

The lifecycle scripts are macOS and Linux only. On Windows, create the environment by hand from PowerShell in the checkout root, and repeat the pip install -e line after updating the checkout:

py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[viewer,tui]"
.venv\Scripts\vibe-view.exe --version

The desktop app runs from that environment too, with the caveat recorded there: the Windows target has not been verified on a real Windows machine.

Desktop integration (macOS)¶

./scripts/install.sh --with-electron --dock --link-bin /opt/homebrew/bin

--dock pins the source-backed vibe-view.app to the Dock. --link-bin DIR writes marked vibe-viewer and deprecated vibe-view launchers into an existing, writable directory on your PATH — /opt/homebrew/bin on Homebrew macOS, or ~/.local/bin when that is on PATH — so vibe-view desktop FILE.qvf works from any shell. --adopt-desktop lets this checkout take over a source app installed by another one.

Both integrations are recorded: uninstall.sh removes them along with the installation, and re-running install.sh with the same flags refreshes them after the checkout or environment moves.

The wheel contains the Python browser, terminal and headless surfaces, but not the Electron source that vibe-view desktop runs. That command requires a source checkout. Apple Silicon macOS packages built from electron/ include their own Python/PyVista/VTK runtime and need no Python setup; trusted signing and notarization remain release steps. The desktop app covers installation, the setup screen, the Finder association and the Linux and Windows notes.

Updating¶

./scripts/update.sh              # fast-forward the current branch
./scripts/update.sh --dev        # switch to main and update
./scripts/update.sh --release    # switch to the release branch and update
./scripts/update.sh --skip-git   # reinstall the checked-out source only
./scripts/update-desktop.sh      # source + Python + the Electron app

Desktop revision checks resolve the installer within the current Git project, including standalone and nested source checkouts. A target revision without the safe desktop update protocol is refused before switching the checkout.

Quit every desktop window before update-desktop.sh. It refreshes the source-backed Electron app owned by this checkout — including its displayed version — and synchronizes the Electron engine to the reviewed lockfile version. It never overwrites an app installed from a DMG: a published macOS package uses Help → Check for Updates.

Repair and removal¶

Quit every desktop window and any running CLI or browser-server launch first.

./scripts/reinstall.sh              # rebuild modes, leave Git alone
./scripts/reinstall.sh --desktop    # also refresh Electron and the source app
./scripts/uninstall.sh --dry-run    # show what would go
./scripts/uninstall.sh

Reinstall is transactional: the previous environment survives until the new one installs and verifies.

Uninstall removes the dedicated viewer environment, a recognizable direct-download Electron runtime in this checkout, a macOS source app owned by this checkout, and the Dock tile or command link created by install.sh. It never removes packaged apps, apps owned by another checkout, your QVF files, settings, recents, logs, or the app-managed environment under $XDG_DATA_HOME/vibe-view/venv. --keep-desktop retains the Electron download and the source app.

The cached interpreter selection is removed only when it points into the environment being deleted.

Building a wheel locally¶

./scripts/install.sh    # also installs the `build` frontend
./scripts/build.sh

build.sh auto-detects .venv, cleans the local build output and writes dist/vibeview-*.whl. For a custom environment set VIBE_VIEW_VENV or VIBE_VIEW_VENV_PYTHON. If it reports no usable vibe-viewer virtualenv found, run install.sh; if it reports a missing build frontend, run update.sh --skip-git.

scripts/make_wheel.sh is the separate release-publisher workflow — it builds and validates both the wheel and the source distribution, writes checksums and stages the website download. Use build.sh for ordinary local packaging.

Comparing lifecycles across the toolset¶

For a side-by-side comparison of install, update, repair and removal across vibe-viewer, vibe-qc, vq and vibe-basis — including profile selection, ownership markers, legacy adoption and what each uninstall keeps — see the toolset lifecycle guide in the vibe-qc documentation.

Launcher records¶

install.sh --link-bin keeps its directory inventory outside the checkout at $VIBE_PRIVATE_ROOT/vibe-view/state/<checkout-hash>/bin-links. If the variable is unset, the root is $XDG_STATE_HOME/vibe-private, or ~/.local/state/vibe-private when XDG_STATE_HOME is unset. Paths must be absolute and outside all Git checkouts and object stores. Private directories use mode 0700 and the inventory uses mode 0600.

The next link or unlink operation verifies and migrates a legacy .vibe-view-bin-links file before removing the old copy. A dry run does not move it. Keep the same private root for install, update and uninstall so each operation can find the same inventory. This does not relocate virtualenvs.