Neptune 3 UI - Install

Before you start, first, you must install all of the components in the Qt Automotive Suite, as described in Install Qt Automotive Suite. Once you have installed Qt Automotive Suite, you can run Neptune 3 UI on your desktop or on a target device, like Intel NUC, by starting it on the command line.

Alternatively, you can also build and run Qt Automotive Suite including Neptune 3 UI from the source code. The corresponding steps are described below. Then, you can modify any part of the code to experiment.

Run Neptune 3 UI from a Qt Automotive Suite Installation

Neptune 3 UI depends on Qt Application Manager and Qt IVI to provide support for both a Center Console display and an Instrument Cluster. It also uses the Qt IVI plugins and its ivigenerator to generate and access various services. Neptune 3 UI offers a multi-process application model using a central System UI and various apps. The System UI provides an application launcher to start and stop apps; it also acts as a full-fledged compositor. Additionally, the Qt Creator Plugin for Qt Application Manager lets you develop and deploy apps using Neptune 3 UI.

To run the binary in your Qt installation, locate it in the default installation folder:

  • On Linux, it's in /home/<your-user-name>/Qt/<qt-version>/gcc_64/neptune3
  • On macOS, it's in /Users/<your-user-name>/Qt/<qt-version>/clang_64/neptune3
  • On Windows, it's in C:/Qt/<qt-version>/msvc2017_64/neptune3

In case you chose a different folder during installation, locate the binaries in <installation-folder>/Qt/<qt-version>/<compiler>/neptune3>.

If you use Qt Automotive Suite on an embedded device, then your Neptune 3 UI binary is in /opt/neptune3/. Launch Neptune 3 UI with the following command in your terminal:


Note: Some functionality in Neptune 3 UI as well as additional apps can use SSL, particularly to access web services via HTTPS. If you're developing on Qt for Windows, then you need to have OpenSSL installed. For more information, see Qt for Windows - Requirements.

Run Neptune 3 UI from Source

To explore Neptune 3 UI by building all components from the source code yourself, refer to the following instructions.


Neptune 3 UI supports the following platforms:

  • macOS (single-process)
  • Linux desktop (single-process)
  • Linux desktop (multi-process)
  • Windows (single-process)

Multi-process UI or Single-process UI

Multi-process UI is the preferred mode. When in multi-process mode, apps run independently in separate processes, as Wayland clients. In this case, the System UI acts as a Wayland server, compositing the app windows in its own QML scene, as regular QML items.

In comparison with single-process mode, all app code run in the same QML scene and process as the System UI itself. For more details, see Single-Process vs. Multi-Process Mode.


  • Qt 5.12 or higher
  • To support multi-process mode, your Qt installation must include the qtwayland submodule, and be built with Open GL ES (-opengl es2 -opengles3).


Build and Run

  1. Clone the repositories mentioned in Install Qt Automotive Suite.
  2. Build Qt Application Manager against Qt 5.15. For more detailed build instructions, see Qt Applicaton Manager Installation.
  3. Build Qt IVI against Qt 5.15. For more detailed build instructions, see Installation.
  4. Run the following command in a terminal, to build Neptune 3 UI:
  5. Locate your neptune3-ui build directory, then run the following command:
    ./neptune3-ui -r

    Note: Use -r to ignore any pre-existing database cache and create a new one by (re)scanning all info.yaml files in the builtin-apps-manifest-dir and installed-apps-manifest-dir. The default value is false. For more information, see Qt Application Manager Configuration.

By default, the Neptune style is used and am-config-neptune.yaml is the default configuration file. To load the LUCEE style for Neptune 3 UI, you must specify -c am-config-lucee.yaml when you start Neptune 3 UI.

Develop with Neptune 3 UI using Qt Creator

When you have cloned, built, installed the project, and configured all of its prerequisites, you can use QtCreator as your development tool. The following instructions describe how to build and run a project:

  • Start QtCreator and open the Neptune 3 UI project file,
  • Open your project's run configuration in Run. In Run configuration, choose "neptune3-ui".
  • Finally, select the Run button or click Ctrl + R to build and run the project.

Note: On Windows, when Neptune 3 UI is built and installed, a neptune3-ui_wrapper.bat is generated to be able to find the required Qt libraries. Run this wrapper instead of the executable file.

© 2019 Luxoft Sweden AB. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.