Installation¶

Note

The published 0.6.3 source archive and its checksums are available from the official updates endpoint. The Sketcher GitHub mirror has no published source snapshot yet. These are separate publication routes.

The commands below use vibe-sketch, which remains supported. The preferred vibe-sketcher launcher requires a rename-aware build; use the substitutions in names and compatibility for other examples in this manual.

Choose an installation route¶

Route	What you install separately	Best starting point
Self-contained macOS package	Nothing for local drawing and input preparation	The chosen release’s DMG/ZIP and checksum; see desktop
Release wheel	A supported Python environment and the wheel’s dependencies	Install a release wheel; the browser bundle is included
Source checkout	Python, Git and Node.js for building the browser	Install from a checkout
Source desktop launcher	The source environment and reviewed Electron runtime	Browser and desktop setup

The current source tree and an older release package can have different setup requirements. Use the release notes for your exact package, particularly for macOS Python bundling. Optional naming, viewer and queue integrations are separate from the basic drawing and input-preparation workflow.

Self-contained macOS app¶

The macOS package built by the current desktop tooling supports Apple Silicon on macOS 14 or newer. It contains Python, RDKit, QVF support and the browser editor. Download the DMG or ZIP for the chosen release, verify its checksum, and move vibe-sketch.app to Applications. Nothing else needs installing; the editor works offline. See the desktop manual for first-launch signing information and release acceptance. A local package build does not mean that an artifact has been published.

What you need for a source or wheel installation¶

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-sketcher 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-viewer and vibe-scheduler 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://vibyverse.com/vibe-sketcher/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. The self-contained macOS app already includes these dependencies and does not use this setup procedure. Wheel publication is separate from the published source archive and desktop installers. Use only a wheel explicitly linked by the selected release.

Install from a checkout¶

Extract the published source archive linked above, or use an existing authorized checkout. From its 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.

An extracted archive has no Git history. Install it with install.sh; to update an archive installation, obtain and verify a later published archive. The Git update commands below apply only to a clone with an accessible configured remote.

Option	Effect
`--extras PROFILE`	`core` (default), `test` (the test suite and linters, with the `publication` backend its figure tests need, as CI installs it), `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`	Reuse an existing browser build; desktop installation still requires a built app
`--with-electron`	Install the reviewed Electron runtime and source launcher
`--dock`	Pin the macOS launcher; requires `--with-electron`
`--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, reinstall Python and rebuild the browser
./scripts/update-desktop.sh    # also refresh the source desktop app
./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.

Every update rebuilds the browser with npm ci and npm run build. Node.js and npm are required; if npm is missing, the updater stops before fetching or reinstalling. A failed browser build stops the update with a nonzero exit status. Fix the build problem and rerun with --skip-git before starting the updated app.

If you have already built web/dist for the source you are installing, you can explicitly reuse it with --reuse-web-build. This option requires an existing nonempty web/dist/index.html; it does not verify that the bundle matches the source. Use it only when you have checked that match. It also works with update-desktop.sh. --dry-run previews rebuilding or reuse without fetching, installing or changing files.

Optional extras¶

Pip extras declare optional dependencies. The installer’s --extras option accepts its named profiles, not arbitrary pip extra names. Companion packages not available on an index must be installed from their supported source first.

Extra	Installs	For
`qvf`	`qvf-writer[numpy,validate]` 0.6 or newer	QVF, the vibe family’s file format and vibe-sketcher’s default for documents. Published on no index: `install.sh --qvf-path DIR` installs it from a qvf checkout at toolkit release v0.6.0 or later; vibe-sketcher 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-scheduler (imported as `vq`; the distribution was called `vq` before 0.26.10). Published on no index: install it from a vibe-scheduler checkout first.
`view`	`vibeview`	Opening the 3D structure in vibe-view. Published on no index either; install from a vibe-viewer checkout first.
`publication`	resvg_py 0.5.0, svg2pdf-py 1.1.0	Whole-scheme PNG and PDF, DPI control and embedded PDF fonts.
`opsin`	py2opsin 1.2.0 (OPSIN 2.9.0)	Structures from systematic, CAS-style and trivial names that vibe-qc’s naming engine does not know. Needs a Java runtime, 8 or newer, on `PATH` or in `JAVA_HOME`; the desktop app bundles neither.
`all`	`publication`, `opsin`	Every optional capability that resolves from a package index.

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

For browser development, keep the Python API and Vite running in separate terminals. From the checkout root, start the API on the proxy’s fixed port:

.venv/bin/vibe-sketch serve --port 8766

In the second terminal:

cd web
npm ci
npm run dev

Open the address printed by Vite (normally port 5173). Vite forwards /api and /health to 127.0.0.1:8766; it does not discover an API that moved to another port. The explicit --port above fails if occupied, making that mismatch visible. Stop your own conflicting server or deliberately adjust the proxy in web/vite.config.ts when another port is required.

Hot reload updates the development UI. It does not rebuild the web/dist bundle used by the normal Python server or source desktop app; run npm run check and npm run build in web/ before checking those surfaces. http://localhost:5173/spike.html is the canvas spike’s measurement page (see the canvas spike notes).

Install the environment, browser app and source desktop launcher together:

./scripts/install.sh --extras dev --with-electron
# Add --dock on macOS to pin the launcher.

Desktop installation requires a built browser app. Install Node.js first, or use --no-web only when web/dist is already built. The selected virtualenv’s Python runs the reviewed Electron installer and is recorded only after success.

./scripts/update-desktop.sh accepts the same options as update.sh, fast-forwards the checkout, reinstalls Python, rebuilds the browser and refreshes this checkout’s source launcher. Packaged apps and source apps owned by another checkout are preserved. Revisions without the safe desktop update protocol are refused before switching. --dry-run changes nothing; --skip-git uses the current tree. update.sh --desktop is equivalent.

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-sketcher 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.

From the activated environment, vibe-sketch desktop [FILE] launches the native window from any directory and checks or installs the runtime for you. It uses that environment’s Python for the server; quitting the window ends the command. See the desktop CLI options.

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.

After an update that changes file types, use --refresh-app to refresh the Applications copy. Both source and packaged macOS apps offer Open With for .qvf, .vsk, .mol, .sdf, .rxn, .cdxml, .ket and .xyz, without replacing the user’s preferred application. QVF and .vsk have the Editor role; the chemistry formats have the Viewer role. QVF imports the shared com.vibe-qc.qvf type, and only .vsk exports a vibe-sketcher type.

The Linux AppImage’s desktop entry lists the corresponding MIME types. The app ships the unchanged QVF declaration and the other format declarations in resources/file-types/. When integrating an AppImage with the desktop, register its desktop entry and, if needed, these MIME files. For an extracted AppImage, the MIME registration commands are:

xdg-mime install --mode user squashfs-root/resources/file-types/qvf-mime.xml
xdg-mime install --mode user squashfs-root/resources/file-types/vibe-sketch-mime.xml

See files in the desktop app for opening, saving and the requirement to save imported QVF results to a different file.

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.

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.
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.
Send an anion to vibe-viewer and check its charge. Use the viewer’s Sketch in vibe-sketcher button, draw a radical, send it back and check its multiplicity and rendered structure.
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-viewer is installed beside vibe-sketcher, 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-sketcher 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.

Publication backend¶

Install with pip install 'vibesketch[publication]' (or pip install -e '.[publication]' in a checkout). The two native bindings are pinned to the reviewed versions. Their common wheel coverage is Apple Silicon macOS, Windows x64 and Linux x64 with glibc 2.35 or newer. Intel macOS, Linux ARM and musl Linux are not supported by the published pair; do not infer platform support from a successful base installation. The base package remains usable without this extra: SVG and legacy single-structure ACS PNG still work.

The PDF binding’s upstream is archived. Its pinned conversion API, physical page size, text embedding and missing-font behavior are covered by tests; upgrading or replacing it requires another dependency review. The supported macOS desktop runtime includes both bindings and their redistribution notices.