Install and maintain the vibe toolset¶

The vibe-qc checkout contains four independently installable tools. You can install only the component you need, keep each tool in its own virtual environment, and maintain it without repeating the manual setup steps from the developer documentation.

These lifecycle scripts support macOS and Linux. They do not require Docker, do not start a container, and do not modify a Docker installation.

At a glance¶

Run every command in this table from the repository root.

Component	Python	Default environment	Install	Verify
vibe-qc	3.11+	`.venv`	`./scripts/install.sh`	`.venv/bin/python -c "from vibeqc import print_banner; print_banner()"`
vibe-view	3.11+	`vibe-view/.venv`	`./vibe-view/scripts/install.sh`	`vibe-view/.venv/bin/vibe-view doctor`
vq	3.12+	`vibe-queue/.venv`	`./vibe-queue/scripts/install.sh`	`vibe-queue/.venv/bin/vq --version`
vibe-basis	3.11+	`vibe-basis/.venv`	`./vibe-basis/scripts/install.sh`	`vibe-basis/.venv/bin/vb --version`

Only vibe-qc builds the native chemistry libraries. vibe-view, vq, and vibe-basis are standalone Python installs unless you explicitly request a combined environment.

Before you start¶

Clone the repository, enter it, and check your Python version:

git clone https://gitlab.peintinger.com/mpei/vibeqc.git
cd vibeqc
python3 --version

The project is currently private. If the clone prompts for credentials or returns 401, request read-only project access as described in Installation.

Run the lifecycle scripts as your regular login user, without sudo. Operating-system package installation may need sudo, but the source checkout, virtual environments, viewer desktop runtime, and user services should have one regular-user owner.

Every entry point supports both of these safe discovery commands before an installation exists:

./COMPONENT/scripts/install.sh --help
./COMPONENT/scripts/install.sh --dry-run

For vibe-qc itself, replace ./COMPONENT/scripts/ with ./scripts/.

Choose standalone or combined installation¶

The dedicated environments in the table are the simplest default. They avoid dependency conflicts, keep companion tools independent of the native vibe-qc build, and let you update or uninstall one component without disturbing the others.

Use a combined vibe-qc environment only when one Python process must import the companion package:

./scripts/install.sh --extras viewer-gpu  # vibe-qc plus browser-capable vibe-view
./scripts/install.sh --extras basisopt    # vibe-qc plus vibe-basis

The standalone vibe-view installer is the recommended way to get all viewer modes, including the desktop and terminal interfaces. The standalone vibe-basis installer is the recommended way to run basis optimization against external codes.

Install each component¶

vibe-qc¶

Use vibe-qc when you want the molecular or periodic chemistry engine:

./scripts/install.sh
source .venv/bin/activate
python -c "from vibeqc import print_banner; print_banner()"

The default follows the public release branch, builds or verifies all native dependencies, creates .venv, installs the [test] profile, and verifies the C++ extension. The first native build normally takes 15 to 40 minutes.

Useful alternatives:

./scripts/install.sh --dev                 # follow main
./scripts/install.sh --current             # keep the checked-out Git revision
./scripts/install.sh --extras dev          # developer dependencies
./scripts/install.sh --with-openblas       # build vendored OpenBLAS
./scripts/install.sh --python python3.13   # choose an interpreter

See Installation for the macOS and Linux system packages required by the native build.

vibe-view¶

Use vibe-view to open QVF files and common chemistry formats without installing vibe-qc:

./vibe-view/scripts/install.sh
source vibe-view/.venv/bin/activate
vibe-view doctor
vibe-view demo --open

The default modes profile installs the CLI, browser viewer, source-backed desktop support, and interactive terminal UI. Electron downloads on the first desktop launch, or you can fetch it during installation:

./vibe-view/scripts/install.sh --with-electron
vibe-view desktop FILE.qvf

Two optional integrations make the source install behave like a native macOS app: --dock pins the source-backed vibe-view.app to the Dock, and --link-bin DIR writes a marked vibe-view launcher into an existing writable directory on your PATH so the command works from any shell. --adopt-desktop transfers the app bundle from another checkout. Uninstall removes the command link and unpins the Dock tile with the installation; see Getting started with vibe-view alone for the exact command.

Choose a smaller profile when appropriate:

Profile	Capabilities
`modes`	Core CLI, browser, desktop server, and TUI; default
`core`	QVF commands, conversion, export, and headless capture
`viewer`	Core plus browser and desktop server
`tui`	Core plus interactive terminal viewer
`all`	Every optional integration
`test`	Viewer and TUI plus test dependencies

Examples for results from other chemistry programs:

vibe-view formats
vibe-view open structure.xyz
vibe-view import calculation.cube
vibe-view tui result.qvf

See Getting started with vibe-view alone for browser, desktop, terminal, headless, and downloaded-wheel workflows.

To build a local wheel after installing the viewer:

./vibe-view/scripts/build.sh

The builder auto-detects vibe-view/.venv, cleans the viewer’s local build output, and writes the wheel under vibe-view/dist/. For a custom environment, set VIBE_VIEW_VENV=/path/to/venv or VIBE_VIEW_VENV_PYTHON=/path/to/python. The release-only make_wheel.sh workflow performs additional validation and stages website artifacts; ordinary users and contributors should use build.sh.

vq¶

Use vq when you want a local or remote job queue:

./vibe-queue/scripts/install.sh
vibe-queue/.venv/bin/vq --version

The default core profile installs the CLI and daemon. Other profiles add the dashboard or development tools:

./vibe-queue/scripts/install.sh --extras web
./vibe-queue/scripts/install.sh --editable --extras dev

Copied installation is the default and is the safer choice for a stable daemon. Use --editable only for development. A remote daemon also needs a supervised systemd-user service on Linux or a launchd user agent on macOS. See The vq calculation queue for the two-host setup, configuration, and service commands.

vibe-basis¶

Use vibe-basis to optimize basis sets with external chemistry programs:

./vibe-basis/scripts/install.sh
vibe-basis/.venv/bin/vb --version

The default standard profile includes SciPy. Select more optimizers or add the co-located vq CLI when needed:

./vibe-basis/scripts/install.sh --extras all
./vibe-basis/scripts/install.sh --with-vq  # requires Python 3.12+

This installation does not build vibe-qc and does not install CRYSTAL, ORCA, or another external engine. Configure those programs separately before running an optimization recipe.

Choose the right lifecycle command¶

Each component provides the same four entry-point names:

Command	Use it when	Git effect	Environment effect
`install.sh`	The component is not installed yet	Component-specific; vibe-qc selects `release`, companions use the current checkout	Creates and verifies a dedicated environment
`update.sh`	Source or installed dependencies should move forward	Fetches and fast-forwards unless `--skip-git` is supported and selected	Reinstalls in place, or replaces with rollback when requested
`reinstall.sh`	Git is correct but the environment is broken or suspect	None	Whole-venv mode rebuilds transactionally and restores the old environment on failure; `--keep-venv` is an explicitly non-atomic in-place repair
`uninstall.sh`	You no longer want this source installation	None	Removes only validated, component-owned targets

Important

vibe-view, vq, and vibe-basis are subprojects in one Git repository. A Git-aware companion update.sh fetches or switches the entire vibe-qc checkout, not only the component directory. Commit or deliberately stash tracked work first. Use --skip-git only where supported when you want to reinstall the currently checked-out source without moving Git.

Always preview an unfamiliar operation first:

./scripts/update.sh --dry-run
./vibe-view/scripts/reinstall.sh --dry-run
./vibe-queue/scripts/uninstall.sh --dry-run
./vibe-basis/scripts/update.sh --dry-run

There is one important Git-default difference:

vibe-qc update.sh follows release unless you select --dev or another branch.
vibe-view, vq, and vibe-basis update the currently checked-out branch unless you select --dev, --release, or --branch NAME.

Run --help on the exact script before using a branch selector, custom virtual environment, profile override, or destructive flag.

Common maintenance workflows¶

Update the current installation¶

./scripts/update.sh
./vibe-view/scripts/update.sh
./vibe-queue/.venv/bin/vq self-update --accepted-report vX.Y.Z
./vibe-basis/scripts/update.sh

Use vq self-update or vq admin update when the selected vq environment owns a running supervised daemon. Direct lifecycle scripts fail closed for serving environments; only the managed transaction owns the checkout, venv, queue pause, and verified service restart as one durable operation.

Update the vibe-view desktop app¶

Quit every source-backed vibe-view window first, then run either command:

./vibe-view/scripts/update.sh --desktop
./vibe-view/scripts/update-desktop.sh

On macOS, these commands update the source checkout, Python environment, reviewed Electron runtime, and checkout-owned Applications copy. On Linux, they update the checkout, environment, runtime, and wrappers; the app continues to launch through vibe-view desktop because there is no Applications copy. They never overwrite a packaged app installed from a DMG. A packaged macOS app uses Help > Check for Updates; other packaged builds use the current replacement artifact. install.sh --with-electron downloads the runtime and installs the macOS Applications copy in the same step.

Change Python or rebuild a damaged environment¶

For vibe-qc, vibe-view, and vq, request an atomic replacement when changing the base interpreter:

./scripts/update.sh --recreate-venv --python python3.13
./vibe-view/scripts/update.sh --recreate-venv --python python3.13
./vibe-queue/scripts/update.sh --skip-git --recreate-venv --python python3.13

vibe-basis already rebuilds safely on every update:

./vibe-basis/scripts/update.sh --python python3.13

When Git should stay unchanged, use the corresponding reinstall.sh instead. The vq direct-script examples in this section require the selected environment to be inactive; a serving vq daemon must use its managed admin lifecycle.

Change an installed profile¶

./scripts/update.sh --extras dev
./vibe-view/scripts/update.sh --extras tui
./vibe-queue/scripts/update.sh --skip-git --recreate-venv --extras web
./vibe-basis/scripts/update.sh --extras all

The direct vq command requires the selected environment to be inactive. For a serving managed daemon, pass the profile override through its configured update script instead, for example vq admin update vibeqc-queue --update-script-arg=--recreate-venv --update-script-arg=--extras --update-script-arg=web. vq self-update deliberately has no profile option; it preserves the installed profile while moving to one exact source pin.

vq and vibe-basis preserve their recorded profile when no override is given. vibe-qc defaults to test and vibe-view defaults to modes; repeat --extras on their update or reinstall commands when you intentionally use a non-default profile. An in-place pip update can add a capability but does not guarantee removal of packages left by an older, broader profile. For exact profile behavior, use the script’s --help output as the command-line source of truth.

What uninstall preserves¶

Preview first, then run the component uninstall command:

Component	Removed by default	Preserved by default
vibe-qc	The checkout-owned Python environment	Source checkout, native dependencies, build caches, and calculation data
vibe-view	Dedicated environment, checkout Electron runtime, and checkout-owned source app	Packaged apps, QVF files, settings, recents, logs, and app-managed data
vq	Dedicated environment	Queue state, job history, workspaces, logs, config, service units, and `/opt/vq` installs
vibe-basis	Dedicated environment	Source, configuration, caches, calculations, and external-program output

Viewer users can retain the downloaded Electron runtime and source app with --keep-desktop. Viewer uninstall also removes a cached interpreter selection only when that record points into the environment being removed; other viewer configuration and window state remain.

vq data removal is deliberately separate and irreversible. Read the complete preview before using --purge-state, --purge-config, or --all. State purge is refused while queued work exists unless --force is also supplied. vq does not remove systemd units, launchd agents, or multi-user /opt/vq deployments on your behalf.

Ownership, rollback, and concurrency safety¶

The scripts protect installations in four ways:

A dedicated environment receives a marker tied to its exact checkout.
Replacement and removal refuse foreign, malformed, symlinked, system, home, checkout-container, and Git-metadata targets.
Replacement keeps the previous environment beside the target until the new install verifies. A failure restores the previous environment.
A shared checkout and target lock prevents two toolset operations from changing the same Git tree or environment concurrently.

If a command says another lifecycle or native-build operation is active, wait for that operation to finish and retry. Do not delete lock files manually.

An environment created before ownership markers existed is not adopted automatically. After inspecting it, preview an explicit one-time adoption:

./scripts/reinstall.sh --adopt-legacy --python /path/to/external/python3 --dry-run
./vibe-view/scripts/reinstall.sh --adopt-legacy --python /path/to/external/python3 --dry-run
./vibe-queue/scripts/reinstall.sh --adopt-legacy --python /path/to/external/python3 --dry-run

For example, the complete vibe-view replacement and removal forms are:

./vibe-view/scripts/install.sh --force --adopt-legacy \
    --python /path/to/external/python3
./vibe-view/scripts/update.sh --recreate-venv --adopt-legacy \
    --python /path/to/external/python3
./vibe-view/scripts/reinstall.sh --adopt-legacy \
    --python /path/to/external/python3
./vibe-view/scripts/uninstall.sh --adopt-legacy \
    --python /path/to/external/python3

The root vibe-qc and vq scripts use the same option roles; run the selected script with --help because install adoption requires its replacement flag.

Adoption succeeds only when trusted PEP 610 metadata points to the exact current checkout. A foreign marker is never adopted. vibe-basis has no legacy path because its standalone lifecycle started with ownership markers; move an unmarked environment aside after manual inspection and install a new one.

Troubleshooting¶

`No usable venv found, install ... first`¶

An update or build helper found no verified installation. Run the component’s install.sh; do not create a partial environment by copying isolated manual steps from developer documentation.

./vibe-view/scripts/install.sh  # example for vibe-view

Python is too old¶

Install a supported Python and name it explicitly:

./vibe-view/scripts/install.sh --python python3.13

vibe-qc, vibe-view, and vibe-basis require Python 3.11 or newer. vq requires Python 3.12 or newer. Apple’s older /usr/bin/python3 is not a supported runtime for these packages.

The checkout has local changes¶

Git-aware updates refuse to hide or overwrite tracked work. Commit the changes, move them to their own branch, or stash them deliberately, then rerun the same command. Use --skip-git only when the component supports it and you explicitly want to reinstall the current source.

The environment is unmarked or belongs to another checkout¶

Confirm --venv, your current directory, and the checkout path. Use a new environment path when the target belongs to a different checkout. Use --adopt-legacy only for a verified pre-marker installation from this exact checkout.

The viewer desktop did not change¶

Quit the app and run update-desktop.sh. If the app came from a DMG, use its update command or install the current packaged artifact instead. Source lifecycle scripts intentionally do not overwrite packaged apps.

vq refuses to update while the daemon is running¶

For a supervised daemon owned by the selected environment, use vq self-update or vq admin update. Direct --restart-daemon is a retired, fail-closed compatibility spelling. An unsupervised or foreign daemon must be stopped through its own owner before a direct source-stable lifecycle script can proceed safely.

Headless vibe-view capture fails¶

Verify the render path directly:

vibe-view capture-selftest

For a queue-managed lean capture environment, use the transactional ./scripts/update_vibeview_capture_env.sh workflow documented in The vq calculation queue.