Installation — OVITO User Manual 3.16.0 documentation

# Installation

## System requirements

Operating System Compatibility:

Windows:

  Windows 10 (21H2 or later), Windows 11 (21H2 or later) on x86_64 processor architecture.

Linux:

  Ubuntu 21.04+, ALT Linux 10+, RHEL 9+, Debian 11+, Fedora 34+, or compatible distributions with glibc >= 2.28, running on x86_64 processors. Additionally, aarch64 (ARM64) processors are supported on distributions with glibc >= 2.39 (e.g. Ubuntu 24.04+, Fedora 40+, Debian 13+).

macOS:

  macOS 14.0+, Apple Silicon (arm64 architecture).

## Installation instructions

Download a binary program package for OVITO Basic or OVITO Pro from www.ovito.org.

Linux:

  Extract the downloaded .tar.xz archive using the tar utility (e.g. tar xJfv ovito-3.16.0-x86_64.tar.xz for x86_64 or tar xJfv ovito-3.16.0-aarch64.tar.xz for ARM64). This creates a subdirectory containing the program files. Change to that directory and run the application: ./bin/ovito.

Windows:

  Run the installer program `ovito-3.16.0-win64.exe` to install OVITO in a directory of your choice. Follow the on-screen instructions to install OVITO. Note: Windows may prompt you to confirm before running an installer downloaded from a website.

macOS:

  Double-click the downloaded `.dmg` disk image file to open it, agree to the license terms, and drag the Ovito bundle into your `Applications` folder. You can then launch OVITO by double-clicking the application bundle.

Anaconda installation: You can also install the software via the Anaconda package manager from the conda-forge channel (OVITO Basic) or from our own conda channel (OVITO Pro).

Unattended installation: The Windows installers support unattended installation via command-line parameters /S and /D from an administrator command prompt. Furthermore, Windows versions of OVITO are available as .zip archives here and can simply be extracted to a directory of your choice (Microsoft Visual C++ Redistributable may need to be installed separately).

## Installing the OVITO Python module

To use OVITO Pro’s functionality in standalone Python scripts, install the OVITO Python module in your Python environment. It can be used for free and doesn’t require a license key. Refer to this section for detailed instructions.

## Running OVITO remotely

You may want to visualize simulation data stored on a high-performance computing (HPC) cluster. For remote use, consider the following options:

1. Linux remote desktop with VirtualGL + VNC:

> Use a VirtualGL + VNC setup to enable OVITO to leverage the remote machine’s graphics hardware. Consult the VirtualGL website for setup details. Ensure the remote machine supports running desktop applications and ask your HPC cluster administrator about compatibility.

2. Local installation with remote file access:

> Install OVITO on your local computer and use its integrated SSH file transfer feature to open files stored on the remote machine.

Note

The OVITO desktop application cannot function via SSH connections using X11 forwarding, as it requires direct access to graphics hardware. Starting ovito from an SSH terminal without further measures will likely result in errors or a blank application window.

## Troubleshooting

If you experience installation issues, visit the OVITO user forum for support. OVITO Pro users can also contact customer support directly. The OVITO team will be happy to help you.

Common installation issues and solutions:

> - Linux troubleshooting

> - Windows troubleshooting

> - macOS troubleshooting

### Linux

Missing shared object files or broken links

  Error

  Starting the desktop application ovito or the script interpreter ovitos may fail with the following error:

      ./ovito: error while loading shared libraries: libQt6DBus.so.6:
              cannot open shared object file: No such file or directory

  This error is typically caused by broken symbolic links in the `lib/ovito/` sub-directory of the OVITO installation after extracting the installation package for Linux on a Windows computer.

  Solution

  Reinstall OVITO by extracting the .tar.xz archive on the target machine. Do not transfer the directory tree between different computers after it has been extracted, because this can easily break symbolic links between files.

Missing XCB system libraries

  Error

  You may see the following error when running ovito on a Linux machine:

      qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
      This application failed to start because no Qt platform plugin could be initialized.
      Reinstalling the application may fix this problem.
      Available platform plugins are: minimal, offscreen, vnc, xcb.

  In this case, OVITO cannot find the required `libxcb-*.so` set of system libraries, which might not be preinstalled on new Linux systems.

  Solution

  Install the required system libraries using your system’s package manager:

      # On Ubuntu/Debian systems:
      sudo apt install libxcb1 libx11-xcb1 libxcb-glx0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
               libxcb-randr0 libxcb-render-util0 libxcb-render0 libxcb-shape0 libxcb-shm0 \
               libxcb-sync1 libxcb-xfixes0 libxcb-xinerama0 libxcb-xinput0 libxcb-xkb1 libxcb-cursor0 \
               libfontconfig1 libfreetype6 libx11-6

      # On CentOS/RHEL systems:
      sudo yum install libxcb xcb-util-cursor xcb-util-image xcb-util-keysyms xcb-util-renderutil xcb-util-wm

  Debian users should also pay attention to this thread in the OVITO support forum.

LD_LIBRARY_PATH overrides OVITO’s bundled Qt libraries

  Error

  Launching ovito may fail with an error such as:

      ./bin/ovito: /usr/lib/x86_64-linux-gnu/libQt6Core.so.6: version `Qt_6.10' not found (required by ovito)

  or a similar message pointing to an incompatible copy of a shared library needed by the program.

  Solution

  OVITO ships its own Qt libraries in `lib/ovito/`. If the environment variable `LD_LIBRARY_PATH` lists a system directory like `/usr/lib/`, the dynamic linker loads the wrong libQt6Core.so.6 before OVITO’s own version, causing the mismatch above. Either start OVITO with a clean library path

      env -u LD_LIBRARY_PATH ./bin/ovito          # temporarily ignore LD_LIBRARY_PATH

  or remove the offending directories from `LD_LIBRARY_PATH` in your shell configuration.

Missing Vulkan support on headless servers, containers, or virtual machines

  Error

  On a Linux machine without a GPU, or one where the Vulkan runtime is not installed, ovito or ovitos may print messages such as:

      Failed to load vulkan: Cannot load library vulkan: vulkan: cannot open shared object file: No such file or directory
      initInstance: No Vulkan library available
      Failed to create platform Vulkan instance

  followed by an error reporting:

      Could not initialize the Vulkan graphics backend. This typically means no compatible GPU or
      graphics driver was found.

  OVITO’s rendering engine relies on the Vulkan API even when only software (CPU-only) rendering is needed, for example when running batch jobs on a headless HPC cluster or inside a Docker container without GPU passthrough. The same error can also occur when using the standalone OVITO Python module installed via `pip` in a regular Python interpreter, and invoking a rendering function such as `ovito.vis.Viewport.render_image()`.

  Solution

  Install the Vulkan loader library together with Mesa’s software Vulkan driver (Lavapipe), which emulates a GPU on the CPU and works without any physical graphics hardware:

      # On Ubuntu/Debian systems:
      sudo apt install libvulkan1 mesa-vulkan-drivers

      # On CentOS/RHEL/Fedora systems:
      sudo yum install vulkan-loader mesa-vulkan-drivers

  Without administrator privileges, for example on a shared HPC cluster, install the driver into your conda environment instead. Note that the Vulkan loader does not search the conda environment’s `share/vulkan/icd.d/` directory on its own, so the location of the driver manifest must be made known to it using the `VK_DRIVER_FILES` environment variable:

      conda install -c conda-forge mesa-lavapipe
      export VK_DRIVER_FILES=$CONDA_PREFIX/share/vulkan/icd.d

  Lavapipe is a software renderer and will be considerably slower than a hardware-accelerated GPU driver. If the machine does have a GPU, install the vendor’s native Vulkan driver instead (e.g. the proprietary NVIDIA driver, or `mesa-vulkan-drivers` for AMD/Intel GPUs, which most distributions already include).

### Windows

Windows 7 not supported

  Error

  If you try to run OVITO 3.7 or later on a Windows 7 computer, it will fail with the error “The procedure entry point CreateDXGIFactory2 could not be located in the dynamic link library dxgi.dll”.

  Solution

  Modern versions of OVITO are based on the Qt6 cross-platform framework, which requires Windows 10 or later to run. Windows 7 has reached its end of life and is no longer supported. Please upgrade your Windows operating system.

### macOS

OVITO Pro license activation fails

  Error

  License activation fails due to an issue with the local license information store (file path `$HOME/.config/Ovito/LicenseStore.ini`). Please check if file access permissions are correctly set. OVITO Pro requires read/write access to this filesystem path.

  Solution

  OVITO Pro requires read/write access to `$HOME/.config/Ovito/` for storing the license activation.

  - If this directory does not exist, OVITO Pro will attempt to create it. If permission issues arise, check ownership of `$HOME/.config/`.

  - This directory may be owned by the system administrator (root), preventing modifications by applications running under your personal user account. In such cases, a system administrator must grant write access.

  In many cases, the issue stems from the parent directory, `$HOME/.config/`, being owned by the wrong macOS user account. This directory serves as the canonical storage location for application configuration data on Linux/Unix systems. Unlike Linux, macOS does not create `$HOME/.config/` by default; instead, individual applications such as OVITO create it when first run. As a result, its ownership and permissions may vary depending on which user account initiated its creation.

  If `$HOME/.config/` was originally created by the system administrator (root), your personal user account may lack write access, preventing OVITO Pro from modifying it. This causes license activation to fail. To fix this issue:

  - Ask your system administrator to create `$HOME/.config/Ovito/` and grant write access to your user account.

  - Alternatively, follow this guide to correct ownership of `$HOME/.config/` yourself.

  If changing ownership is not possible, you can set the environment variable `XDG_CONFIG_HOME` (info) to point to a different writable directory:

      export XDG_CONFIG_HOME=/path/to/writable/directory

  This redirects OVITO Pro to store its licensing information in a user-specified location.