Installation

What you need

• Python 3.12 or newer. Debian and Ubuntu also need the matching python3-venv package.

• Git, to clone the repository.

• Node.js 22 or newer only if you build the browser shell (web/) or the desktop shell (electron/) from source.

• On Linux, the X rendering libraries, which RDKit’s drawing code links for SVG and PNG figures: on Debian or Ubuntu, sudo apt-get install libxrender1 libxext6. Desktop installations have them already; minimal containers and headless servers often do not, and vibe-sketch then names them when you export a figure. macOS needs nothing.

There is no compiler and no native build: vibesketch is pure Python plus wheels. RDKit is a core dependency and installs as a wheel. vibe-qc, vibe-view and vibe-queue are not installed and not required.

Note

There is no pip install vibesketch yet: the package is not published on any index. Install from a checkout, as below.

Install a release wheel

When a release is published, its versioned wheel is hosted under https://vibe-qc.com/vibe-sketch/docs/_static/downloads/. Download the version named in the release notes, verify its published SHA256 checksum, and install it into a dedicated environment:

python3 -m venv .venv
.venv/bin/python -m pip install /path/to/vibesketch-X.Y.Z-py3-none-any.whl
.venv/bin/vibe-sketch serve

The wheel includes the browser app, document schema, third-party notices and the corresponding Indigo/InChI source. Python dependencies install separately; Git and Node.js are unnecessary for this route. Downloaded desktop apps guide you through creating an environment and installing their matching wheel. Release tooling is present, but the first release has not been published yet.

Install from a checkout

From the repository root:

./scripts/install.sh
source .venv/bin/activate
vibe-sketch --version

install.sh is for macOS and Linux. It creates a dedicated environment under .venv at the repository root and installs the package in editable mode. Run every lifecycle script as your regular login user, without sudo, so the checkout and the environment keep one consistent owner.

Option	Effect
--extras PROFILE	core (default), test, docs, all or dev (test + docs + release tooling)
--python BIN	Interpreter used to create the environment (default python3)
--venv PATH	Where the environment goes (default .venv)
--force	Replace an environment this script created
--naming-path DIR	Make vibe-qc’s naming engine importable from the vibe-qc checkout DIR
--qvf-path DIR	Install qvf-writer from the qvf checkout DIR, so documents save as QVF
--no-web	Do not build the browser app (built by default when npm is available)
--dry-run	Print what would happen and change nothing

Or, for a plain development install:

python -m venv .venv
.venv/bin/pip install -e '.[test,dev]'

Update a checkout

./scripts/update.sh            # fast-forward the current branch and reinstall
./scripts/update.sh --dev      # switch to main first
./scripts/update.sh --skip-git # reinstall from the current tree

The update only fast-forwards. A branch that has diverged, or a working tree with uncommitted changes, stops it before anything changes.

Optional extras

Every optional integration is an extra of the vibesketch distribution, so pip install -e '.[name]' (or install.sh --extras) is the whole setup.

Extra	Installs	For
qvf	qvf-writer 0.4 or newer	QVF, the vibe family’s file format and vibe-sketch’s default for documents. Published on no index: install.sh --qvf-path DIR installs it from a qvf checkout at toolkit release v0.4.0 or later; vibe-sketch is tested against the release CI’s QVF_TAG names. The archive format remains QVF version 1. Without a supported writer, documents save as .vsk.
queue	vibe-queue	Submitting jobs through vibe-queue (imported as vq; the distribution was called vq before 0.26.10). Published on no index: install it from a vibe-queue checkout first.
view	vibeview	Opening the 3D structure in vibe-view. Published on no index either; install from a vibe-view checkout first.
all	nothing yet	Every optional integration that resolves from a package index. Every runtime extra above needs a sibling checkout, so this is empty today.

test, dev, docs and release are tooling extras: the test suite, the linters, the Sphinx toolchain and the wheel build.

The browser app and the desktop shell

install.sh builds the browser app when Node.js 22 or newer is installed; vibe-sketch serve then serves it with the API. To build it by hand:

cd web && npm ci && npm run build

npm run dev in web/ serves the app with hot reload on port 5173 and forwards /api to a server on port 8766. http://localhost:5173/spike.html is the canvas spike’s measurement page (see the canvas spike notes).

The Electron desktop shell is implemented and runs the same app in a native window. It is available from an authorized checkout independently of public release packages. The shell is documented in electron/README.md. Install its reviewed runtime without npm:

python3 electron/install-electron.py
python3 electron/install-electron.py --check

The installer verifies the release’s SHA256 checksum and atomically replaces the runtime. On macOS it brands and ad-hoc signs a vibe-sketch app in an Applications folder, with a launcher tied to this checkout. Open it from Finder or Spotlight; add --dock when installing to pin it to the Dock. No Apple developer account is needed. With npm available, npm start in electron/ uses the same runtime and the checkout’s .venv.

Use --refresh-app after updating the checkout, and rerun the installer after moving it. Existing packaged apps and source apps owned by other checkouts are preserved; --refresh-app --adopt-app explicitly adopts another checkout’s source app. --uninstall --dry-run previews removal; --uninstall removes only the recognized runtime and source app owned by this checkout, leaving npm-managed runtimes and user data intact. Run it as your regular user. File associations and the vibe-sketch desktop command remain desktop work in roadmap WP 2.7.

Browser acceptance tests

The optional browser extra supplies the pinned Playwright test tools:

python -m pip install -e '.[test,browser]'
python -m playwright install chromium
(cd web && npm ci && npm run check && npm run build)
VIBESKETCH_REQUIRE_BROWSER=1 python -m pytest tests/test_phase2_exit.py tests/test_browser_*.py -q

On Linux, use python -m playwright install --with-deps chromium to install the browser’s system libraries too. The browser CI job requires these tests and consumes the built web artifact. Its trace and failure screenshot are retained per test in test-results/browser/. Ordinary Python test runs skip browser tests when their optional tools, browser or web bundle are unavailable; VIBESKETCH_REQUIRE_BROWSER=1 makes missing prerequisites a failure.

The accessibility tests load the pinned axe-core development dependency from web/node_modules. They check the shell, menus, species and reaction panels, Inputs form and calculation states against the WCAG 2.2 A/AA rules, and exercise keyboard navigation and focus retention. Ketcher’s canvas is excluded from this shell audit.

The canvas regressions compare hidden and visible mounts with small and large molecules, check the zoom percentage against the rendered SVG scale, and verify that later resizing preserves a zoom chosen by the user.

The exit test imports ethanol through the browser. From that prepared sketch, the default ORCA B3LYP/def2-SVP input takes one click, including automatic 3D embedding. Choosing vibe-qc and submitting takes two actions. The test checks the downloaded input and the listed run. Its MCP counterpart calls new_document, write_inputs, submit_jobs and show_runs through the protocol. Both use real chemistry and input writers with a stand-in queue; execution against external programs needs the integration check below. Startup coverage delays the session and initial document responses, checks disabled actions and keyboard shortcuts, then imports successfully after readiness. A failed startup must keep its error and retry hint visible.

Checking installed integrations

The automated exit tests do not run ORCA or vibe-qc. Before a release, check the installed programs with a separate queue configuration and state directory, selected through VQ_CONFIG_DIR and VQ_STATE_DIR. Register ORCA and vibe-qc there and run that queue’s daemon in a terminal.

1. Import a small molecule such as water. Submit an ORCA calculation and a vibe-qc calculation from both the browser and vibe-sketch submit. Save the documents and follow every run with vibe-sketch runs until it finishes successfully. Submit and cancel a disposable run too.

2. Run a vibe-qc optimisation with frequencies. Open its result QVF and compare the imported conformer with the final geometry, including atom order, charge and multiplicity.

3. Send an anion to vibe-view and check its charge. Use the viewer’s Sketch in vibe-sketch button, draw a radical, send it back and check its multiplicity and rendered structure.

4. Stop the temporary servers and daemon. Record program versions, results and any follow-up issues in the issue tracker, keeping private paths and calculation files out of the repository.

When vibe-view is installed beside vibe-sketch, the optional tests in tests/test_qvf.py also exercise its actual hand-off reader and verify charge, multiplicity, atom order and coordinates for an anion and a radical.

Naming

Names come from vibe-qc’s naming engine, vibeqc_naming. It ships inside vibe-qc today (vibe-qc #536), so vibe-sketch does not depend on it: without it, the app and the CLI say naming is not installed and everything else works. With a vibe-qc checkout, --naming-path makes it importable without building vibe-qc.