MOptima
Chapter 12

Installation and Platform Notes

Source: docs/manual/12-installation-and-platform-notes.md

Platform requirements

Windows

The Windows package includes the application itself, but not the separately licensed xTB engine. Unzip and run MOptima.exe; if xTB is missing, MOptima can download it on first launch or from Tools > Download > xTB.

Linux

Run MOptima on a local desktop session (the monitor attached to the machine, or a full remote desktop such as VNC, NoMachine, or xrdp).

Remote display through SSH X11 forwarding (for example MobaXterm or ssh -X) is not supported: the 3D viewer requires OpenGL/WebGL rendering that X11 forwarding cannot provide, resulting in a black or empty viewer window.

If the application reports a missing Qt platform plugin on startup, install the xcb cursor library and try again:

  • Ubuntu / Debian: sudo apt install libxcb-cursor0
  • Fedora / RHEL: sudo dnf install xcb-util-cursor

macOS

The first time you open the app, macOS Gatekeeper may block it because the package is not notarized. Right-click the app and choose Open, or remove the quarantine attribute:

xattr -dr com.apple.quarantine MOptima.app

Installing the xTB engine

xTB powers the semi-empirical calculations (GFN methods). It is not bundled with MOptima on any platform.

Automatic installation

On Windows, macOS, and Linux, MOptima checks for xTB at startup:

  1. If xTB is not found, a dialog offers to install it automatically.
  2. Click OK to download and install to ~/.moptima/engines. A progress bar is shown.
  3. Click Cancel to skip permanently. MOptima will not ask again; use the menu entry or a manual method below instead.

If an installation attempt fails, MOptima will offer to retry on the next launch.

You can also start the installation at any time from the menu: Tools > Download > xTB.

The installer downloads from the official xTB release first. If the connection is slow or fails (common behind restrictive networks), it automatically falls back to mirror sources. To force a specific download source, set the MOPTIMA_XTB_URL environment variable to a direct URL of the xTB archive before starting MOptima.

Manual installation

MOptima looks for xTB in this order: the bundled engines folder (legacy installs only), ~/.moptima/engines/*/bin/xtb, then any xtb or xtb.exe on your PATH. Any of the following works:

  • conda: conda install -c conda-forge xtb
  • Homebrew (macOS): brew install grimme-lab/qc/xtb
  • Manual download (Windows): download xtb-6.7.1pre-windows-x86_64.zip from the xTB GitHub releases page and extract it so the binary sits at ~/.moptima/engines/xtb-6.7.1/bin/xtb.exe
  • Manual download (Linux): download xtb-6.7.1-linux-x86_64.tar.xz from the xTB GitHub releases page and extract it so the binary sits at ~/.moptima/engines/xtb-6.7.1/bin/xtb
First-launch dialog offering automatic xTB installation.

Notes for users in mainland China

  • The automatic installer handles slow GitHub connections by switching to mirrors automatically; no configuration is needed.
  • For conda installs, configuring the Tsinghua conda-forge mirror (mirrors.tuna.tsinghua.edu.cn) first is strongly recommended.
  • On Apple Silicon Macs, brew install compiles xTB from source and may take 20+ minutes; the conda route is much faster.