Vulkan Renderer

Vulkan is a low-level graphics API used to program the GPU to perform graphics rendering and other tasks. It is a modern, high-performance replacement of the legacy OpenGL API. It is supported by all desktop and mobile GPU vendors, and support is included in all recent graphics drivers, although you may need to install the small Vulkan API loader manually.

Release 5.8 officially enables the new Vulkan backend renderer as the default, replacing the OpenGL renderer. Releases before 5.8 use OpenGL.

As of HEAVY.AI Release 6.0, OpenGL is fully removed, leaving Vulkan as the only available driver. As a result, the renderer-use-vulkan-driver program option has been removed. Please remove any references to that program option from your configuration files.

For Release 5.7 and up, a Vulkan API loader library is required to be installed regardless of which renderer you use. See the Troubleshooting guide below for details on how to install the Vulkan API loader.

Advantages of Using Vulkan

Vulkan provides the following improvements over OpenGL in the backend renderer:

Vulkan is designed specifically for speed. The Vulkan renderer is often 2 times faster than OpenGL, and performance will improve in the future.

Enabling Vulkan

In Release 5.8, Vulkan is the default. OpenGL rendering is deprecated and removed in Release 6.0. For Release 5.7, the Vulkan renderer is considered a Beta feature, and OpenGL is the default driver.

OmniSci recommends using the Vulkan renderer unless you have hit a blocking issue with Vulkan. Although the Vulkan driver is reliable and stable, it has not yet had wide external usage compared to its OpenGL counterpart and may be prone to unforeseen configuration issues; see Troubleshooting below for guidance on known issues. Having Vulkan enabled helps us to find and address additional issues while a reliable fallback exists to ensure a smooth, less risky transition.

To enable Vulkan rendering in releases lower than 6.0, set the configuration option renderer-use-vulkan-driver=true. Note that this is the default in Release 5.8.

To disable Vulkan rendering and use the OpenGL legacy renderer, set the configuration option renderer-use-vulkan-driver=false. Note that this is the default in Release 5.7.


Follow these steps if you receive error messages when using Vulkan.

Bare-Metal Installs

You might see the following error when trying to start a rendering-enabled server for the first time:

error while loading shared libraries: cannot open shared object file: No such file or directory

If you receive this error, you need to install the Vulkan API loader:

  • CentOS: sudo yum install vulkan

  • Ubuntu: sudo apt install libvulkan1 --no-install-recommends

You might experience a server crash or get errors on startup like the following:

Oct 21 17:09:33 omnisci_server[61162]: LLVM ERROR: inconsistency in registered CommandLine option

If this occurs, HEAVY.AI recommends setting the VK_ICD_FILENAMES to the Nvidia Driver Manifest variable before starting the server.

  • Ubuntu/Debian: export VK_ICD_FILENAMES=$(ls /usr/share/vulkan/icd.d/nvidia*)

  • CentOS/Redhat: export VK_ICD_FILENAMES=$(ls /etc/vulkan/icd.d/nvidia*)

Although /usr/share/vulkan/icd.d and /etc/vulkan/icd.d are the most commonly used paths, the Vulkan loader looks in all the following locations: /etc/vulkan/icd.d /usr/local/etc/vulkan/icd.d /usr/local/share/vulkan/icd.d /usr/share/vulkan/icd.d $HOME/.local/share/vulkan/icd.d

If the server has been installed as a service, check the name of the Nvidia icd json file with the following command:

  • Ubuntu/Debian: ls /usr/share/vulkan/icd.d/nvidia*

  • CentOS/Redhat: ls /etc/vulkan/icd.d/nvidia*

Then, add the output as an Environment to the HEAVY.AI server Service section with the following command:

sudo vi /usr/lib/systemd/system/heavydb.service

  • Ubuntu/Debian [Service] Environment="VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json"

  • CentOS/Redhat [Service] Environment="VK_ICD_FILENAMES=/etc/vulkan/icd.d/nvidia_icd.json"

Then, run sudo systemctl daemon-reload.

As a last resort, you can remove the package mesa-vulkan-driver from the OS.

  • CentOS: sudo yum remove mesa-vulkan-drivers

  • Ubuntu: sudo apt remove mesa-vulkan-drivers

For a summary of how to install the Vulkan loader on various Linux distributions, see

Docker Installs

If you run the server in a Docker container and you see an error similar to the following in your logs, even with the proper drivers installed, your NVIDIA Docker runtime may be out of date:

Backend rendering disabled: Error creating Vulkan instance: Vulkan Error: VK_ERROR_INCOMPATIBLE_DRIVER

To resolve, try upgrading the nvidia-docker2 package on your system.

Last updated