A Github Action to install the Vulkan SDK and runtime library.

It also supports installing SwiftShader and Lavapipe software rasterizers.

• Features
• Usage
• Action Reference
  • Inputs
  • Outputs
  • Environment Variables
• About Vulkan and the Vulkan SDK
  • What is Vulkan?
  • What is the Vulkan SDK?
  • What is the Vulkan SDK for ARM?
  • What is the Vulkan Runtime?
  • What are Installable Client Drivers (ICDs)?
  • Where to find Vulkan Documentation
• Software Rasterizers
  • SwiftShader
    • What is SwiftShader?
    • Installing SwiftShader
    • Registering SwiftShader as Vulkan Driver
  • LLVMPipe and Lavapipe
    • What is LLVMPipe? What is Lavapipe?
    • Installing Lavapipe
    • Registering Lavapipe as Vulkan Driver
  • Troubleshooting Loader Issues
• License
• Development Reminder

This action has the following features:

• This action can be used to install the Vulkan SDK in your Github Action workflows.
  • The action automatically retrieves the latest Vulkan SDK version if no specific version is provided.
• The installation of optional SDK components is supported.
• The action can be used to install the Vulkan Runtime (Windows only) using download retries and automatic version lowering.
• This action allows you to install just the Vulkan Runtime, without the full Vulkan SDK (Windows only).
• The action supports Github Actions cache (for the Vulkan SDK and runtime).
  • The size of the installed SDK is reduced to achieve a smaller cache package size (Windows only).
• The installer supports runners for Windows, Linux, macOS, Windows-ARM, and Linux-ARM.
  • The repository https://github.com/jakoch/vulkan-sdk-arm is used to build and package the Vulkan SDK for ARM64 runners.
• The action can be used to install the software rasterizers: Google SwiftShader and Mesa Lavapipe.
  • The repository https://github.com/jakoch/rasterizers is used to build and package both rasterizers.

jobs:
  build:
    runs-on: ${{ matrix.config.os }}
    strategy:
      matrix:
        config:
          - { name: "Windows",       os: windows-latest }
          - { name: "Ubuntu",        os: ubuntu-latest }
          - { name: "MacOS",         os: macos-latest }
          - { name: "Ubuntu 22 Arm", os: ubuntu-22.04-arm }
          - { name: "Ubuntu 24 Arm", os: ubuntu-24.04-arm }
          - { name: "Windows Arm",   os: windows-11-arm }

    steps:
      - name: Install Vulkan SDK
        uses: jakoch/install-vulkan-sdk-action@v1
        with:
          # You can set the Vulkan SDK version to download.
          # Defaults to latest version, if version not set.
          vulkan_version: 1.3.231.1
          optional_components: com.lunarg.vulkan.vma
          install_runtime: true
          cache: true
          stripdown: true

          # You can install a software rasterizer.
          install_swiftshader: true
          install_lavapipe: true

You can find all Inputs and Outputs and their default settings in the action.yml file.

The following inputs can be used as steps.with keys:

The following output variables are available:

The following environment variables are set:

The Khronos Vulkan API is an explicit, low-overhead, cross-platform graphics and compute API. Vulkan provides applications with control over the system execution and the system memory to maximize application efficiency on a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.

The Vulkan SDK enables Vulkan developers to develop Vulkan applications.

Links: https://vulkan.org/ | Vulkan SDK | Vulkan SDK Docs | Vulkan Tools | Vulkan @ gpuinfo

The Vulkan Software Development Kit (SDK) is a collection of tools, libraries, headers, and validation layers needed to develop Vulkan applications.

It includes:

• Vulkan API headers: Required for compiling Vulkan applications.
• Validation layers: Help debug and validate Vulkan API usage.
• SPIR-V tools: For compiling and optimizing shader code.
• Sample code and documentation: To help developers learn Vulkan.
• Loader and drivers: Ensures proper Vulkan function dispatch.

The Vulkan SDK is provided by LunarG and is essential for developers who want to build and test Vulkan-based applications.

The Vulkan SDK for ARM is an unofficial custom build SDK based on the official tarballs for Linux and build on Github Actions runners (ubuntu-24.04-arm, ubuntu-22.04-arm).

The installer uses releases from https://github.com/jakoch/vulkan-sdk-arm.

Currently (02-2025), KHRONOS has no plans to modify the official tarball to include prebuilt ARM binaries or to release or update the Ubuntu packages for ARM.

The Vulkan Runtime (VulkanRT) refers to the essential Vulkan libraries and drivers installed on a system, allowing Vulkan applications to run.

It typically includes:

• The Vulkan loader: Manages Vulkan function calls and interfaces with GPU drivers.
• Runtime libraries: Required to execute Vulkan applications.

Unlike the SDK, the Vulkan Runtime is typically installed automatically by your GPU driver (from NVIDIA, AMD, or Intel) and is needed for running Vulkan applications.

This installer enables you to install the latest Vulkan Runtime for development, allowing you to test your applications with the most up-to-date runtime and bundle it for redistribution when packaging your application.

An ICD is the real Vulkan driver provided by a GPU vendor (or software rasterizer) that implements the Vulkan API.

When an application calls Vulkan functions (like vkCreateInstance()), those calls go through the Vulkan loader, which then passes them to one or more ICDs that are installed on the system.

Each ICD is described by a small JSON file, for example:

C:\lavapipe\share\vulkan\icd.d\lvp_icd.x86_64.json
C:\SwiftShader\vk_swiftshader_icd.json

These JSON files tell the Vulkan loader:

• the path to the driver file
• the architecture (x64, arm64)
• and contain additional metadata, like version or entrypoint

In order to work with a driver, you have to register them in the Windows registry.

When you run the Vulkan Info Tool (vulkaninfoSDK.exe):

1. The Vulkan loader checks the registry at HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers.
2. It finds all .json ICD files listed there.
3. It loads each ICD and queries its capabilities (e.g., from AMD, NVIDIA, Intel, SwiftShader, Lavapipe, etc.).
4. It reports back all devices and properties in your system.

• HTML
• PDF

• Vulkan Documentation
• Khronos Vulkan Registry
• vulkan.gpuinfo.org by Sascha Willems

• Vulkan SDK: Release Notes, Download Page, API
• Vulkan Configurator: Readme, Changelog
• Vulkan Loader: Layer Configuration, Loader Debugging Guide
• Vulkan Validation Layer: Readme, Coverage Report / Error Database
• Vulkan API Capture and Replay - GFXReconstruct: Usage
• Vulkan Profiles Toools: Overview, Changelog, Whitepaper

• Vulkan Discord, Reddit, StackOverflow, Mastodon

• Community Layers and Tools: Vulkan Introspection Layer, MangoHud

This action allows you to optionally install the CPU-based software rasterizers, SwiftShader and Lavapipe, which enable Vulkan API rendering on systems without dedicated GPU hardware.

Swiftshader, developed by Google, delivers a high-performance CPU-based implementation of the Vulkan and OpenGL ES APIs, ensuring graphics rendering on systems without GPU acceleration.

You can install SwiftShader using install_swiftshader: true.

The install location can be changed using swiftshader_destination.

The default location for Windows is C:\Swiftshader.

The installation folder will contain 3 files:

vk_swiftshader.dll
vk_swiftshader_icd.json
vulkan-1.dll

To make SwiftShader available as a Vulkan renderer, you must register it as an Installable Client Driver (ICD).

This is done by placing its JSON manifest file, which identifies the ICD and provides the path to the driver DLL, into the Windows registry.

You can do this using PowerShell with the following command:

reg add "HKLM\SOFTWARE\Khronos\Vulkan\Drivers" /v "C:\Swiftshader\vk_swiftshader_icd.json" /t REG_DWORD /d 0 /f

This allows the Vulkan loader to enumerate SwiftShader among available ICDs and instantiate it as needed by Vulkan applications.

Once registered, you can verify that the driver loads correctly and inspect its capabilities using the Vulkan SDK’s vulkaninfo tool:

vulkaninfoSDK.exe -j -o swiftshader_profile.json

Get-Content -Raw swiftshader_profile.json

This command generates a JSON file (swiftshader_profile.json) containing detailed information about the SwiftShader Vulkan driver, including supported extensions, features, and device properties.

The json file should contain an entry capabilities.device.properties.VkPhysicalDeviceProperties with a line similar to: "deviceName": "SwiftShader Device (LLVM 10.0.0)".

To confirm that, you can use jq to extract the device name:

jq -r '.capabilities.device.properties.VkPhysicalDeviceProperties.deviceName' swiftshader_profile.json

This should output a line similar too:

SwiftShader Device (LLVM 10.0.0)

Mesa's LLVMpipe is a CPU-based software rasterizer in the Mesa 3D Graphics Library that enables OpenGL rendering without dedicated GPU hardware. It leverages the LLVM compiler infrastructure to translate graphics operations, including vertex processing, shader execution, and rasterization of points, lines, and triangles, into LLVM Intermediate Representation (IR). This IR is then dynamically compiled into optimized machine code for the host CPU architecture (such as x86, x86_64, or ppc64le), delivering a flexible and performant fallback renderer for systems lacking GPU support.

Mesa's Lavapipe is CPU-based software driver for the Vulkan API. Like LLVMpipe, it uses LLVM to compile Vulkan shaders into native machine code, providing a fully functional Vulkan implementation that runs entirely on the CPU. Lavapipe serves as a critical fallback for environments without compatible GPU drivers, such as virtual machines or headless systems, ensuring Vulkan applications can still run when no hardware acceleration is available.

In short:

• LLVMpipe = OpenGL on the CPU
• Lavapipe = Vulkan on the CPU

As this action focuses on providing the Vulkan SDK and drivers, we focus on the installation of Lavapipe.

You can install Lavapipe using install_lavapipe: true.

The install location can be changed using lavapipe_destination.

The default location for Windows is C:\Lavapipe.

The installation folder will contain 3 files:

vulkan_lvp.dll
vulkan_lvp.lib
share\vulkan\icd.d\lvp_icd.x86_64.json

To make Lavapipe available as a Vulkan renderer, you must register it as an Installable Client Driver (ICD).

This is done by placing its JSON manifest file, which identifies the ICD and provides the path to the driver DLL, into the Windows registry.

You can do this using PowerShell with the following command:

reg add "HKLM\SOFTWARE\Khronos\Vulkan\Drivers" /v "C:\lavapipe\share\vulkan\icd.d\lvp_icd.x86_64.json" /t REG_DWORD /d 0 /f

This allows the Vulkan loader to enumerate Lavapipe among available ICDs and instantiate it as needed by Vulkan applications.

Once registered, you can verify that the driver loads correctly and inspect its capabilities using the Vulkan SDK’s vulkaninfo tool:

vulkaninfoSDK.exe -j -o lavapipe_profile.json

Get-Content -Raw lavapipe_profile.json

This command generates a JSON file (lavapipe_profile.json) containing detailed information about the SwiftShader Vulkan driver, including supported extensions, features, and device properties.

The json file should contain an entry capabilities.device.properties.VkPhysicalDeviceProperties with a line similar to: "deviceName": "llvmpipe (LLVM 21.1.4, 256 bits)".

To confirm that, you can use jq to extract the device name:

jq -r '.capabilities.device.properties.VkPhysicalDeviceProperties.deviceName' lavapipe_profile.json

This should output a line similar too:

llvmpipe (LLVM 21.1.4, 256 bits)

The Vulkan loader has added logging functionality that can be enabled by using the VK_LOADER_DEBUG environment variable.

set VK_LOADER_DEBUG=error,warn,info

See Loader Debugging.

All the content in this repository is licensed under the MIT License.

Copyright (c) 2021 Jens A. Koch

This section contains development field notes and acts as reminder for other devs and myself.

• Step 1. Bump version number in package.json

• Step 2. Run npm run npm:install to install the dependencies

• Step 3. Run npm run all to generate a bundled package in dist

  • or simply open package.json and click the desired command via script section

• Step 4. Update changelog

• Step 5. Commit the changes, including the dist folder, then push

• Step 6. Tag the commit with the full version number:

  git tag v1.2.3
  git push origin v1.2.3

• Step 7. Force push the v1 tag to this commit:

  git tag -f v1
  git push origin v1 -f