# Installation

Binary program packages of OVITO for Linux, Windows, and macOS can be downloaded from www.ovito.org.

## System Requirements

OVITO requires a 64-bit operating system and runs on processors with x86-64 or arm64 architecture. The graphical user interface of OVITO requires 3D graphics hardware with support for the OpenGL programming interface (OpenGL 2.1 or newer). In general it is recommended that you install the latest graphics driver provided by your hardware vendor before running OVITO as some older drivers may not fully support modern OpenGL specifications, which can lead to compatibility problems.

## Installation instructions

Linux:

  Extract the downloaded `.tar.xz` archive file using the tar command: tar xJfv ovito-3.7.0-x86_64.tar.xz. This will create a new sub-directory containing the program files. Change into that directory and start OVITO by running the executable ./bin/ovito.

Windows:

  Run the installer program `ovito-x.y.z-win64.exe` to install OVITO in a directory of your choice. Note that Windows might ask whether you really want to launch the installer, because it was downloaded from the web and it is not digitally signed.

macOS:

  Double-click the downloaded `.dmg` disk image file to open it, agree to the program license, and drag the Ovito application bundle into your `Applications` folder. Then start OVITO by double-clicking the application bundle.

## Running on remote machines

Note that the OVITO desktop application cannot be run through an SSH connection using X11 forwarding mode, because the software requires direct access to the graphics hardware (OpenGL direct rendering mode). If you simply run ovito in an SSH terminal, you will likely get failure messages during program startup or just a black application window.

It is possible to run OVITO on a remote machine through an SSH connection using a VirtualGL + VNC setup. For further information, please see the www.virtualgl.org website. In this mode, OVITO will make use of the graphics hardware of the remote machine, which must be set up to allow running applications in a desktop environment. Please contact your local computing center staff to find out whether this kind of remote visualization mode is supported by the HPC cluster(s) you work on.

## Python module installation

The OVITO Pro program packages ship with an integrated Python interpreter (ovitos) that gets installed alongside with the desktop application, allowing you to execute Python scripts written for OVITO. Optionally, you can install the `ovito` Python module into existing Python interpreters on your system (e.g. Anaconda or the standard CPython interpreter) in case you would like to make use of OVITO’s functionality in script-based workflows. Please refer to this section for further setup instructions.

## Troubleshooting

If you run into any problems during the installation of OVITO, you can contact the developers through our online support forum. The OVITO team will be happy to help you. The most commonly encountered installation issues are described here:

### Linux

Error

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

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

This error is typically caused by broken symbolic links inside the `lib/ovito/` sub-directory after extracting the OVITO installation archive on a computer other than the target machine.

Solution

Reinstall OVITO by extracting the installation archive on the target machine. Do not transfer the program directory tree between different computers after it has been extracted.

Error

You may see the 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 fresh Linux systems.

Solution

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

    # On Ubuntu/Debian systems:
    sudo apt-get 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

    # On CentOS/RHEL systems:
    sudo yum install libxcb 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.

Error

OVITO depends on the OpenSSL libraries (version 1.1.*). If they are not present on your system, starting ovito will typically fail with the error:

    error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

Solution

Please install the OpenSSL 1.1.x libraries using the package manager of your Linux distribution. OVITO depends on the presence of the shared libraries `libssl.so.1.1` and `libcrypto.so.1.1` in your system directory. On CentOS 7, for example, you should install the package openssl11-libs. On old Ubuntu 16.04 systems, the OpenSSL 1.1 libraries are not available through the package manager. In this case, please download an older OVITO package (e.g. version 3.5.4), because past OVITO releases used to contain copies of the OpenSSL libraries. You can then copy the missing library files into the new program directory to make them available to the current OVITO version.