Installation — OVITO Python Reference 3.15.3-dev-HEAD-b1e9512d documentation

# Installation

Note

If you are an OVITO Pro user, there usually is no need for you to install the `ovito` Python module. See OVITO Pro integrated interpreter.

## Using pip

If you are using a regular Python interpreter (not Anaconda, see below), you can install the OVITO Python module from the PyPI repository with the pip command:

    pip install -U ovito

For further information, please refer to https://pypi.org/project/ovito/.

## Using conda

If you work with an Anaconda, Miniconda, or Miniforge environment, you should use the following conda install command line:

    conda install --strict-channel-priority -c https://conda.ovito.org -c conda-forge ovito=3.15.3-dev-HEAD-b1e9512d

The `ovito` conda package includes both the `ovito` Python module and the graphical desktop application OVITO Pro. The latter requires a paid license if you want to use it.

Important

The `ovito` conda package is hosted in our conda channel https://conda.ovito.org. It can easily be confused with the ovito package found in the popular conda-forge channel. The latter includes only OVITO Basic but not the Python module. To make sure you’ve installed the right package version, run conda list and check if the source channel of the installed package is https://conda.ovito.org and not conda-forge.

## OVITO Pro integrated interpreter

The OVITO Pro program package includes a preconfigured Python interpreter (commonly referred to as “ovitos”). This interpreter comes pre-equipped with the `ovito` Python module and all other things necessary to execute Python code within the OVITO Pro desktop application. The ovitos interpreter may also be invoked externally, from a system terminal, to run standalone Python scripts on the command line:

    ovitos [-o <file.ovito>] [-g] [<script.py>] [args...]

The ovitos executable is located in the `bin/` subdirectory of OVITO Pro for Linux, the `Ovito.app/Contents/MacOS/` directory of OVITO Pro for macOS, and the main application directory of OVITO Pro for Windows. It should not be confused with ovito, which is the executable that launches the graphical desktop application. Both programs access the same integrated Python engine and ovitos serves as a stand-in for the python executable, which allows running Python scripts from the command line in OVITO Pro’s integrated interpreter.

Let’s say you’ve written a simple Python script file named `hello.py`:

    import ovito
    print("Hello world, this is OVITO %i.%i.%i" % ovito.version)

You can execute the script from a system terminal as follows:

    user@linux:~/ovito-pro-3.15.3-dev-HEAD-b1e9512d-x86_64/bin$ ./ovitos hello.py
    Hello, this is OVITO 3.15.3-dev-HEAD-b1e9512d

ovitos is a console program that behaves almost like a regular python interpreter. It lets you easily run scripts on remote machines or computing clusters that don’t possess a graphical display. Any command line arguments following the script name will be passed to your Python program via `sys.argv`. Invoking ovitos without a script filename starts an interactive interpreter session.

While you can also use any other Python interpreter to execute Python programs that import the `ovito` module (after installing the module in that interpreter), ovitos relieves you from installing the `ovito` module and provides a few extra capabilities, which are described in the following sections.

### Preloading session state

The -o command line option tells ovitos to load an `.ovito` session state file before executing your script. This allows you to preload an existing data pipeline or visualization setup that you have previously prepared using the OVITO Pro desktop application. All script actions will subsequently be performed in the context of this preloaded session. This approach can save you programming work because things like modifiers and the camera setup already get loaded from the state file, and you don’t need to set everything up programmatically in your script anymore.

### Graphical mode

The -g command line option of ovitos starts a graphical program session of OVITO Pro, and the script will be run in the context of this GUI session. This lets you directly observe your script’s actions as they are being executed. This function is useful for debugging purposes if you want to visually check the outcome of your script’s actions during the development phase. Keep in mind that the viewports will only show pipelines that have been inserted into the current scene via `Pipeline.add_to_scene()`.

### Number of CPU cores

OVITO uses all available processor cores by default to perform certain computations. To explicitly restrict the program to a smaller number of parallel threads, use the --nthreads command line parameter, e.g. ovitos --nthreads 1 myscript.py. See Controlling how many processor cores OVITO uses.

### Installing third-party Python modules

ovitos is a preconfigured CPython interpreter with the `ovito` Python package already built in. This makes it possible to run scripts both within the OVITO Pro desktop application as well as through the ovitos command line tool. However, OVITO Pro’s embedded Python interpreter only ships with very few third-party packages, namely NumPy and matplotlib.

If you want to call other third-party Python packages from your script, you can install them in the ovitos interpreter using the usual pip install mechanism. Simply run

    ovitos -m pip install --user <package_name>

from a system terminal to install any package from the PyPI repository. This will make the package also available to scripts running in the context of a graphical OVITO Pro session.

Note

The described approach only applies to OVITO Pro installed via installers from www.ovito.org. If you work with the Anaconda version of OVITO Pro, use the conda install command to add additional packages to the Python interpreter shared by OVITO Pro and your Anaconda environment.

Note

Installing a Python extension via pip that includes native code may fail if it is not compatible with the build-time configuration of the ovitos interpreter. In such a case, using the Anaconda version of OVITO Pro is recommended, which makes installing third-party packages straightforward.

## OVITO Pro Jupyter kernel

OVITO Pro can work as a Jupyter kernel since release 3.12.0. While this kernel behaves like a regular Python 3 kernel, it allows you to execute Python code in the context of the OVITO Pro desktop application, which can be useful for interactive data analysis and visualization tasks. From a Jupyter notebook, you can then launch the OVITO Pro GUI at any time by invoking the `ovito.gui.create_window()` function, which opens the OVITO Pro main window. You can then interactively inspect (and change) pipelines created in your notebook.

The OVITO Pro Jupyter kernel is automatically installed as part of the Python-enabled OVITO conda package. You need to additionally install the `ipykernel` and `ipywidgets` packages from the conda-forge channel if you want to use the kernel. The kernel will appear as a new option in the JupyterLab launcher:

See also

`ovito.gui` module