MOptima
Chapter 12

Installation and Platform Notes

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) and the Molecular Orbital Viewer. 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.