Getting Started — Install, Launch, and Sign In

Qemica runs as a native desktop application on macOS, Windows, and Linux. Installation has two parts: the app itself, and a one-time Python environment that powers the chemistry engine. This section walks you through both, what to expect on first launch, and how to set up your account.

Install on your platform

Download the installer for your operating system and launch, then set up the Python engine environment below.

  • macOS: Download the .dmg — one universal build runs natively on both Apple Silicon and Intel — open it, and drag Qemica.app to /Applications. On first launch, if macOS reports an unidentified developer, go to Security & Privacy and click Open Anyway.
  • Windows: Download Qemica.exe, run the installer, choose an install location, then launch from the Start menu or desktop shortcut. On Windows the chemistry engine runs inside WSL2 (the scientific Python stack is Linux-native) — see the engine setup below.
  • Linux: Download the .x86_64 binary or AppImage, make it executable (chmod +x Qemica or right-click → Properties → Permissions → Allow executing file), then double-click or run ./Qemica.

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 "~/Library/Application Support/Qemica/engine/.venv" --python 3.14, then uv pip install --python "~/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).
  • Linux: identical, with the environment at ~/.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 ~/.qemica/engine/.venv, and set Config → Engines → Environment to ~/.qemica/engine/.venv/bin/python. Qemica drives the engine through wsl.exe automatically.
  • 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.
  • 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 a Get-started card offers three bundled sample molecules (benzene, aspirin, caffeine) and a four-step quickstart — one click loads a sample into Model, no engine required.
  • 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.
Security and privacy.
  • Your password is never sent to Qemica servers — authentication happens directly between you and Supabase over HTTPS.
  • The access token is stored in the OS keychain (Windows Credential Manager, macOS Keychain, or the Linux system keyring).
  • All chemistry data — molecules, calculations, results — stays on your computer and never leaves unless you explicitly export it.