Getting Started — Install, Launch, and Sign In

Install on your platform

The public download is currently for macOS. Windows and Linux support exists in the codebase but public installers are still planned.

• macOS: Download Qemica.dmg — one universal build runs natively on both Apple Silicon and Intel — open it, and drag Qemica.app to /Applications.
• The macOS installer is signed with a Developer ID certificate and notarized by Apple. If Gatekeeper cannot verify it, download a fresh copy from qemica-lab.com rather than bypassing the warning.
• Windows and Linux: public installers are not available yet. The Windows engine design uses WSL2; platform-specific installation instructions will appear here when those builds ship.

Set up the Python engine (one-time)

The chemistry engine installs as a Python package (quchemy) into a small environment you create once with uv. No Python needs to be preinstalled — uv downloads the right interpreter itself. On macOS and Linux the first-launch setup dialog has an Install automatically button that runs every step below for you (with live per-step status and the full output shown verbatim if anything fails); the same commands stay visible with a Copy button if you prefer the terminal, and Qemica finds the environment automatically afterwards.

• Install uv (one line): curl -LsSf https://astral.sh/uv/install.sh | sh — a single small binary, works on macOS, Linux, and inside WSL.
• macOS: uv venv "$HOME/Library/Application Support/Qemica/engine/.venv" --python 3.14, then uv pip install --python "$HOME/Library/Application Support/Qemica/engine/.venv/bin/python" <the quchemy wheel URL shown in the app>. That installs the engine and its scientific stack (NumPy, SciPy, PySCF, OpenFermion, RDKit, cclib, geomeTRIC). Use $HOME, not ~ — a tilde inside quotes is not expanded and you get a folder literally named ~.
• Linux: identical, with the environment at $HOME/.local/share/Qemica/engine/.venv.
• Windows (WSL2): install WSL once (wsl --install in PowerShell), then run the same uv commands inside the WSL shell against $HOME/.qemica/engine/.venv, and set Config → Engines → Environment to $HOME/.qemica/engine/.venv/bin/python. Qemica drives the engine through wsl.exe automatically.
• Windows: write that override as $HOME/.qemica/engine/.venv/bin/python (or the absolute /home/<your-wsl-user>/… form) — never with a ~. Qemica 0.2.3 and later rewrite a leading ~ for you, but earlier builds pass it to WSL quoted, where the shell cannot expand it, and the engine then reports that it cannot find Python.
• Custom setups: already have conda or a venv with the stack? Skip all of the above and point Config → Engines · Environment at your interpreter or venv root.
• Optional extras can wait — Open Babel formats, D3/D4 dispersion, Qiskit, IBM Quantum runtime, SQD, and the MACE ML potential all install later with one click from Config → Engines.
• ORCA is different: Qemica cannot distribute it, so there is no one-click install. Register for and install your own copy from the ORCA forum (orcaforum.kofo.mpg.de), then set the full path to the orca executable in Config → Engines → External engines and press Test ORCA — it runs a real two-atom calculation and reports the version, plus whether parallel runs work on your machine. Until a working path is set, the Classical (ORCA) backend stays greyed out.
• Verify: launch Qemica (or press Re-check in the setup dialog) — Config → Engines should show your environment as the resolved interpreter and ✓ for pyscf, rdkit, and cclib.

System requirements

• macOS: a recent macOS release, on Apple Silicon (M-series) or Intel.
• Windows: Windows 10 or 11, 64-bit (Intel or AMD), with WSL2 for the engine.
• Linux: a modern 64-bit distribution (Ubuntu, Fedora, Debian, or similar).
• Python: nothing to preinstall — the uv setup above downloads the tested interpreter (3.14) into the engine environment.
• RAM: 8 GB recommended — more helps for larger molecules and quantum simulations.
• Storage: a few hundred MB for the app plus roughly 2 GB for the Python environment (more with optional extras such as the MACE ML potential).

First launch

On first run, Qemica initializes local storage and probes for available engines.

• It creates a local SQLite index and a projects folder in the per-user app data directory (macOS: ~/Library/Application Support/Qemica) to store molecules and calculations.
• It probes the Python engine environment to detect available engines and tools (PySCF, quantum libraries, RDKit, Open Babel, cclib).
• You land on the Home screen, where the Get started card offers bundled samples, a four-step quickstart, and Start guided tour.
• Start guided tour checks that PySCF, RDKit, cclib, and geomeTRIC are ready, creates a Tutorial project, and walks the real Model → Configure → Run → Analyze controls. It never starts by itself, can be skipped at any point, and can be replayed from Config → General.
• Verify the five navigation tabs (Home, Model, Configure, Run, Analyze) are visible, then optionally open Config (avatar menu → Settings) → Engines to confirm PySCF is detected (a checkmark next to the version).

Create and use an account

Qemica uses email and password authentication (backed by Supabase) shared across the desktop app and the Qemica website. Your profile syncs across both; your chemistry data stays local. An account is optional: the first-run dialog has a Skip for now button, the choice is remembered, and you can sign in any time later from the avatar. (The EULA/privacy consent step still applies either way.)

• Sign up: Click the avatar icon in the top-right corner, choose Sign up, and enter your email and password. If email confirmation is enabled, click the link in your inbox, then return and Sign in.
• Sign in: Click the avatar, choose Sign in, and enter your credentials. Qemica caches your session in the OS keychain, so you stay logged in on next launch — even offline.
• Your name defaults to the part of your email before the @, and is editable in your profile.
• If the refresh token expires, Qemica signs you out and asks you to log back in.