Getting Started with the macOS Vulkan SDK

Vulkan SDK Introduction

This guide describes the content, the requirements and procedure for getting started with the Vulkan SDK.

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. The Vulkan SDK includes:

• Vulkan API usage validation thanks to the Khronos Validation layer.
• Vulkan Layers configuration thanks to Vulkan Configurator.
• SPIR-V Shader compilation, optimization and validation thanks to DXC, SPIR-V Tools, SPIR-V Cross and MoltenVKShaderConverter.
• Vulkan Capabilities Viewer. The new and preferred way to identify your devices capabilities, and contribute to an open-source database of GPU capabilities.
• Vulkan system report thanks to Vulkan Installation Analyzer (VIA) and Vulkan Info.
  • Note: The Vulkan Installation Analyzer may be deprecated at some point in the future. The Vulkan loader debugging output has been expanded to replace this tool.

All documentation for the SDK can be found and downloaded online at vulkan.lunarg.com. For a broader overview see the LunarG white paper The State of Vulkan on Apple Devices.

Looking for Validation Layer Binaries for Android?

With each SDK release, a release of the Khronos Validation Layer binaries for Android are released on the Validation layer Repository. The Android binaries are not included in this SDK.

Terminology

MoltenVK

This SDK provides partial Vulkan support through the use of the MoltenVK library which is a "translation" or "porting" library that maps most of the Vulkan functionality to the underlying graphics support (via Metal) on macOS, iOS, iPadOS, and tvOS platforms. It is NOT a fully-conforming Vulkan driver for macOS, iOS, iPadOS, or tvOS devices.

There are two ways to make use of MoltenVK in your shipping Vulkan-based applications. One is to link directly to the MoltenVK static or dynamic library, which will give you direct access to the Vulkan API, and allows for some mixed use with Vulkan and low-level Metal capabilities. This option is not practical if you wish to maintain portability of your Vulkan rendering code across platforms. Mixing of Vulkan and Metal capabilities can be done using the VK_EXT_metal_objects extension. Moreover, you will also sacrifice the ability to use the Vulkan Validation layers. An XCFramework is provided as a static library that can be linked directly to your application if you wish to go this route. Please see the MoltenVK Runtime User Guide on the MoltenVK GitHub for more information about MoltenVK specifics.

For desktop, iOS, and iPadOS applications, the recommended usage model is to use the MoltenVK dynamic library in conjunction with the Vulkan Loader. In this scenario the MoltenVK library takes on the role of the ICD from the point of view of the application and the Vulkan Loader. In this mode, you link only to the Vulkan Loader, and not the MoltenVK library directly. You will include the MoltenVK and the Vulkan Loader dynamic libraries in your application's bundle when distributing your software. When the Vulkan SDK is installed on macOS, these runtime components are placed in system directories and can be easily used during development without embedding them in the app bundle. Even if you decide to ship your application linked to the static MoltenVK library, during development we recommend you make use of the Vulkan Loader and Vulkan Validation Layers as they are a tremendous boon for debugging your Vulkan-based rendering code. NOTE that for Apple's App Store distribution you must use the provided Framework versions of the Vulkan Loader, MoltenVK, and any layers you may wish to distribute with your application as naked .dylib's are not allowed in app store bundles.

Regardless of the method used, your applications are distributed with everything they need to use Vulkan over Metal all included in your application's bundle. No additional system files or runtime components are needed by the end users of your applications on any Apple platform.

System Requirements

• The latest major version of macOS: Used to build all components in the SDK.
• Optionally, the last major version of macOS is by policy also supported. Current these are macOS versions 14 (Sonoma) and 15 (Sequoia).
• The latest version of Xcode (currently 16.0): Required for building apps using this SDK.
• For MoltenVK requirements see the repository.
• The Vulkan SDK loader, validation layers, and other libraries are packaged as Universal Libraries with support for both Intel and Apple Silicon architectures for macOS, and ARM64 and ARM64e for iOS and iPadOS.

Use of the Vulkan SDK

SDK Versioning

The components in this SDK are built with a specific version of Khronos Vulkan API header, whose version is reflected in the SDK's version number. For example, SDK version v.w.xx.0 indicates the SDK uses the Vulkan header revision where:

• "v" is the Vulkan major version
• "w" is the Vulkan minor version
• "xx" is the Vulkan patch version

The last number in the SDK version indicates the revision of an SDK for the given Vulkan header revision. It is used in case it is necessary to release multiple SDKs for the same version of Vulkan.

For example, SDK version 1.1.70.0 indicates the SDK uses Vulkan header revision 1.1.70.

Note: A more recent SDK version number does not indicate an application cannot be developed for earlier Vulkan versions. As well, an older SDK version can not be used to develop applications for a newer version of Vulkan. For example, the 1.1.130.0 SDK can be used to develop Vulkan 1.0 applications but cannot be used to develop applications for Vulkan 1.2. Furthermore, the presence of a 1.2.xx SDK does not necessarily indicate a system can actually run Vulkan 1.2. A Vulkan 1.2 driver is required for applications to use most Vulkan 1.2 functionality.

Note: On macOS, iOS, iPadOS, and tvOS, the Vulkan header number is not a true reflection of the underlying support from MoltenVK (which is currently at Vulkan version 1.2).

Note that there is a version for your Vulkan Loader, and a separate supported version for each physical device on your system.

1. Vulkan Instance Version. This is the version of your Vulkan Loader. If you run vulkaninfo, the Vulkan Instance version is the first item reported. The Vulkan Loader is delivered with your driver update package on most operating systems, but on macOS the loader is shipped as part of the SDK, or is included directly in the MoltenVK library. Most developers will include these files in their macOS application bundles.
2. For each physical device, there is an apiVersion. The apiVersion is the version of Vulkan supported by that device. You can find the apiVersion for each physical device from your vulkaninfo output under the section labeled "Device Properties and Extensions".

Download the SDK

Download the Vulkan SDK from the Download Site. The SDK download file is named with the pattern:

vulkansdk-macos-v.w.xx.0.zip

Install the SDK

NOTE: Installing the SDK updates the Vulkan Loader and MoltenVK libraries in /usr/local, if the installer option [X] System Global Installation is selected.

Double-click the .zip file and run the InstallVulkan application. The Vulkan installer program will ask you for the destination folder to install the Vulkan SDK. It will prompt you for your user password as well as it needs administrative access in order to copy the Vulkan Loader and SDK tools to system folders where your terminal path can locate them. The macOS SDK is intended to be installed anywhere the user can place files such as the user's $HOME directory. An uninstaller is also created and placed in the SDK installation folder.

Installing Optional Components

The VulkanSDK installer can automatically download optional components from the cloud and install them as part of the SDK installation (an Internet connection is required for this).

Install and Uninstall from Terminal

The new macOS installer application can also be run from the command line allowing for unattended/scripted installation and uninstallation. Navigate to the folder containing the InstallVulkan.app bundle, and execute the embedded application directly. You will need to use sudo to give the installer permission to access the system folders, and you must also provide the destination path for the SDK installation files.

sudo ./InstallVulkan.app/Contents/MacOS/InstallVulkan --root "installation path" --accept-licenses --default-answer --confirm-command install

For example, to install into your home folder using a root of "VulkanSDK", and an SDK version of 1.3.275.0, including all optional packages, you would use this command:

sudo ./InstallVulkan.app/Contents/MacOS/InstallVulkan --root ~/VulkanSDK/1.3.275.0 --accept-licenses --default-answer --confirm-command install com.lunarg.vulkan.core com.lunarg.vulkan.usr com.lunarg.vulkan.sdl2 com.lunarg.vulkan.glm com.lunarg.vulkan.volk com.lunarg.vulkan.vma com.lunarg.vulkan.ios

Likewise the maintenance tool can also be used to uninstall an SDK:

sudo ./MaintenanceTool.app/Contents/MacOS/MaintenanceTool --confirm-command purge

The new installer is based on the open-source Qt Installer Framework, and more complete details on all command line options can be found here.

The macOS installer has a command line option to skip the installation of system files, thus negating the need to run with sudo. If you use this option, SDK tools, the loader, and the MoltenVK ICD are not copied to the system folders (/usr/local/lib), and the SDK files are only copied to the specified installation folder. If installed in this manner, the MaintenanceTool program can also be run without administrative privileges. To skip the installation of system files simply add copy_only=1 to the list of command-line parameters for the installer.

SDK System Paths

macOS allows the installation of files to /usr/local which are then in the standard system paths and the loader's search paths for ICDs, if the [X] System Global Files option is selected during installation. The Vulkan installer program will copy the loader, command line tools, and the MoltenVK ICD to these folders. This eliminates the need to set PATH, DYLD_LIBRARY_PATH, VK_LAYER_PATH, and VK_ICD_FILENAMES environment variables in order to use SDK components during development. You should note that macOS does not easily provide support for allowing environment variables to affect the behavior of GUI applications. For developers who rely on the command line for much of their work, these environment variables behave as expected and can be used to override the default behavior.

It is important to note that recent versions of macOS and Xcode have removed /usr/local/lib from the default list of locations to search for dynamic libraries (while it is still for now the recommended place to put non-system global development libraries and tools). The Volk Meta Loader has been updated already to take this into account, and is available as a (recommended) optional SDK component. If you do not include the Vulkan loader in your application bundle, you may need to modify @rpath appropriately to search in /usr/local/lib, or use the DYLD_LIBRARY_PATH environment variable for command line driven applications.

You can manually uninstall and re-install these system files by using the same install scripts that the installer and uninstaller uses and that are provided with the SDK. These are named install_vulkan.py and uninstall.sh To run these scripts, in your terminal navigate to the directory you installed the SDK files into and run:

sudo ./install_vulkan.py

This will copy the SDK files to the appropriate system directories and generate a log file named VULKAN_INSTALL.log in /tmp. This script does require Python 3 (version 3.8 or later recommended) to be installed. If you are using Xcode for development, this will include a sufficiently recent version of Python for you. If not, we recommend using homebrew to get and install Python 3.

To run the uninstall script, navigate to the root directory of the SDK in your terminal and run:

sudo ./uninstall.sh

Note: Since SDK components are copied directly to the /usr/local tree, only a single version of the Vulkan SDK can be active at a time. Using this method, it is possible to switch manually back and forth between SDK versions without having to re-run the installer. You should be aware that if System Integrity Protection is enabled (it normally is), you may need to reboot before the kernel will recognize the new code signatures from these updated files. A work around for rebooting in this scenario is to be sure and remove these files first with ./uninstall.sh and do not just run ./install_vulkan.py repeatedly copying the files over the previous versions.

Vulkan SDK contents

This section describes how the SDK contents are organized.

VULKAN_SDK Tree

The macOS directory is the root of a "system tree" containing Vulkan executables, include files, and libraries in the traditional bin, include, lib structure. This tree contains the Vulkan components such as the loader library and layer libraries. The corresponding iOS directory parallels this, but for iOS hardware development only.

These trees also contains executables, include files, and libraries for various Vulkan-related tools such as glslang, SPIRV-Tools, and others.

It is often useful to point system environment variables (e.g., PATH, DYLD_LIBRARY_PATH) and Vulkan-related environment variables (e.g., VK_LAYER_PATH) to directories in this directory to locate the components found in this tree. In addition VK_ICD_FILENAMES can point to the latest MoltenVK ICD included in the SDK instead of using the system paths.

This can be done with the setup-env.sh script. Remember, these environment variables are not seen by GUI applications launched from Finder or the graphical shell in macOS, even if you put them in the system startup script.

Options for Using Vulkan Support Components

The Vulkan SDK is flexible in the sense that it can support various workflows. Some of these workflows are summarized here.

Create a Bundled Application

Your Xcode project copies all required components from the SDK and places them in the application bundle. This results in a standalone application that can be copied or published anywhere and does not require the user to have an SDK installed.

Using Xcode, add the various components from the SDK to your Xcode project. Configure your project so all required components are in your bundle.

Xcode with SDK Side-Install

Your Xcode project has references to the SDK and requires an SDK be installed on your system. This workflow might be used in a development phase that eventually leads to the bundled application workflow. The SDK installer will copy the appropriate files to your /usr/bin paths so that the Vulkan Loader and MoltenVK ICD are available when you run your project from Xcode.

Set up the runtime environment

If the SDK is not installed to system directories you may need to set environment variables inside the Xcode interface when working with Xcode projects that use SDK components. You may also need to set environment variables in your command shell when running some non-bundled Vulkan applications or other SDK tools from the command line.

A setup script is provided in the top-level directory of your SDK installation to help you easily set the environment variables. Use the source command to load that script into your current shell:

source setup-env.sh

See the note below about environment variables and GUI applications.

Set up the runtime environment manually

Note that on macOS, shell environment variables are not seen by GUI applications launched from the Apple launch services (such as double-clicking an apps icon). In addition, the DYLD_LIBRARY_PATH is considered a security violation and will not function unless SIP (System Integrity Protection) is disabled. This is not recommended, but can be useful during development (but not for a shipping application). Best practice on macOS is to include the Vulkan Loader and/or MoltenVK directly in the application's .app bundle and not disable SIP.

If you are developing on the command line and wish to launch applications primarily from the command line, you can set up the environment using the Terminal application:

Set a convenience variable to point to the SDK:

export VULKAN_SDK=$vulkansdk/macOS

Replace the $vulkansdk above with the actual path to your SDK but include the /macOS part.

Add the bin directory to your PATH to make it easy to run Vulkan Info and the various glslang and SPIRV-Tools installed there:

export PATH=$VULKAN_SDK/bin:$PATH

Add the lib directory to your DYLD_LIBRARY_PATH so that programs find the Vulkan Loader library:

export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH

Tell the Vulkan Loader where to find a Vulkan driver:

export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json

Tell the Vulkan Loader where to find the Vulkan SDK Layers:

export VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d

Verify the SDK Installation

Verify the installation of the Vulkan SDK by running:

• Vulkan Installation Analyzer (VIA) with the command:

$ vkvia

• Vulkan Info with the command:

$ vulkaninfo

Working with Xcode

Using the loader gives your application run-time access to the MoltenVK ICD (or potentially load other Vulkan implementations dynamically) and the Vulkan Khronos Validation layer as well as other helper or emulation layers. You may even want to ship your application with layers embedded in your application bundle.

Configuring Xcode with Environment Variables

If you want your Xcode project to refer to components residing in an SDK instead of bundling these components, you can set environment variables in your Xcode project to point to these components instead of bundling them.

This may be a technique suitable for developers whose workflows are compatible with "pointing" to a specific SDK during their work. It is unlikely that anyone would want to deploy an application that requires an SDK to be present.

Here are some approaches for setting these variables:

Set Variables in Xcode

Xcode has an interface for setting environment variables in the "Scheme" panel. This is a fairly common and straightforward approach.

Inherit Variables From Environment

If you are new to macOS development, it may surprise you that environment variables set in your shell will not be seen by Xcode if Xcode is launched from Launchpad or other desktop GUI. You may be able to pass shell environment settings into Xcode by starting Xcode with open from a bash shell command line where the environment variables are set.

With Xcode versions 7 and later, you may need to enable this behavior:

defaults write com.apple.dt.Xcode UseSanitizedBuildSystemEnvironment -bool NO

System-wide Preferences

Configure the system-wide Preferences for Xcode by adding Custom Paths in the Preference's Locations tab.

Using the Vulkan Loader

As an alternative to using the framework, you can add Vulkan Loader support to your application by adding the Vulkan header files and Vulkan Loader library file individually to your project:

Add the SDK's macOS/include directory to the project's Header Search Paths. Add both the libvulkan.1.dylib and the libvulkan.1.x.yyy.dylib to your application's folder in the Project Navigator. You may have to add a Copy Files step to copy these two files into the compiled project.

libvulkan.1.dylib and libvulkan.dylib are both symbolic links to libvulkan.1.x.yyy.dylib. You may prefer to link only to libvulkan.1.x.yyy.dylib or rename libvulkan.1.x.yyy.dylib to libvulkan.1.dylib or libvulkan.dylib in your project.

Mobile Device Development

As of January 2024, Vulkan Loader support is now available for iOS and iPadOS devices. Layers, however, must be bundled with your application framework, and must be enabled programmatically at instance creation time. More details about this can be found here: The State of Vulkan on Apple Devices.

Vulkan SDK Layers

Vulkan Layers aim at helping Vulkan developers building Vulkan applications by providing Vulkan API usage validation and Vulkan debugging tools.

A Vulkan Layer can intercept all or any subset of Vulkan API entry points. Multiple layers can be chained together to cascade their functionality in the appearance of a single, larger layer.

Vulkan SDK Layers list

The Vulkan SDK for macOS includes the following layers:

Use Vulkan Layers

Vulkan Configurator

Vulkan Configurator is a GUI application designed to make Vulkan Layers features and settings more accessible and intuitive to use, and to improve development iteration time.

A Vulkan application may configure layers when creating a Vulkan Instance. This layers configuration may be overridden using Vulkan Configurator globally or for a selected list of Vulkan applications.

Finally Vulkan Configurator allows using Vulkan Layers from user-defined directories.

Main window	Layers window

Note: This is the recommended approach to use or override Vulkan Layers.

VK_INSTANCE_LAYERS environment variable

Remember that on macOS, environment variables are not seen by GUI applications. However, if working from the command line the Vulkan Layers can be enabled by setting the VK_INSTANCE_LAYERS environment variable to a colon-separated list of layer or extension names, as found in the Vulkan SDK Layers list or within the manifest files.

$ export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation:VK_LAYER_LUNARG_api_dump

Debugging Vulkan applications

Vulkan API Validation with Khronos Validation layer

By design, minimal error checking is done inside a Vulkan driver to avoid API overhead. Applications have full control and responsibility for correct operation. Any errors in how Vulkan is used can result in a crash. The Khronos Validation layer VK_LAYER_KHRONOS_validation can be enabled to assist development by enabling developers to verify their application's correct use of the Vulkan API.

Troubleshooting

Loader Messages

To get debug messages from the loader, export VK_LOADER_DEBUG=all and run your app or vulkaninfo. You will get debugging messages from the loader on stdout when this is set. This is even easier when using Vulkan Configurator to run your apps with validation layers.

Common Problems

Encountered VK_ERROR_INITIALIZATION_FAILED:

This problem can occur when the loader is unable to find an ICD to use. There are a few ways to fix this:

• You can export the VK_ICD_FILENAMES environment variable.
• You can install the ICD in a system directory.
  • Run sudo ./install_vulkan.py from the Vulkan SDK folder if your installation has been compromised.
• If your application is contained in a bundle, you can relink the app to place the driver in the bundle.

Encountered "Could not start Vulkan Info" message in "Vulkan Info" tab of vkconfig.app:

To use the "Vulkan Info" tab in vkconfig.app the SDK files must be copied to your system folders. If your installation has become corrupted ,you can run sudo ./install_vulkan.py from the SDK folder or re-run the SDK installation program.

Encountered VK_ERROR_INCOMPATIBLE_DRIVER:

Beginning with the 1.3.216 Vulkan SDK, the Vulkan Loader is strictly enforcing the new VK_KHR_PORTABILITY_subset extension. The most likely cause of this error message on instance creation is failure to adhere to this extension, which prevents applications on all platforms from selecting by default a non-conformant Vulkan implementation without opting in. MoltenVK is currently not fully conformant, and thus supporting this extension is necessary for building robust and portable Vulkan-based applications that are good citizens in the Vulkan ecosystem.

Opting in is simple. First add the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR bit to your VkInstanceCreateInfo structure's .flags member, then add two instance extensions to your instance extensions list: VK_KHR_portability_enumeration, and VK_KHR_get_physical_device_properties2.

Typically the code to add support for instance extensions looks something like this:

std::vector<const char*>
extNames.push_back(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME);
extNames.push_back(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME);

VkInstanceCreateInfo inst_info = {};
ins_info.flags = VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR;
inst_info.enabledExtensionCount = static_cast<uint32_t>(extNames.size());
inst_info.ppEnabledExtensionNames = extNames.data();

Note that support for the VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME is only required for Vulkan version 1.0.

Loader Search Paths for ICD and Layers

The Vulkan Loader for macOS searches the same paths for ICDs and Layers as the Vulkan Loader for Linux. These paths are described in The Loader And Layer Interface document.

The macOS and iOS loader also looks in the application's bundle for ICD and layer JSON files. It looks in the bundle's Resources/vulkan/icd.d directory for ICD JSON files and in the bundle's Resources/vulkan/explicit_layer.d directory for layer JSON files. The ICD JSON file (MoltenVK_icd.json) can be seen in the bundle shown above.

If the executable is in a bundle, the loader searches the bundle first before searching the system directories.

If you wish to bundle the MoltenVK ICD into your application, you need to put a modified version of the MoltenVK_icd.json file in your bundle's Resources/vulkan/icd.d folder to allow the loader to find the MoltenVK library in your bundle. Assuming that you intend to ship the MoltenVK library in the Frameworks directory, you would make a copy of the file /macOS/share/vulkan/icd.d/MoltenVK_icd.json from the SDK.

Edit this copy to modify the library_path:

Original:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "./libMoltenVK.dylib",
        "api_version" : "1.2.0",
        "is_portability_driver": true
    }
}

Modified:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "../../../Frameworks/libMoltenVK.dylib",
        "api_version" : "1.2.0",
        "is_portability_driver": true
    }
}

Then use this modified file when creating your application bundle.

Application Bundle Structure on macOS

For example, the application bundle for Vulkan Cube (vkcube.app) is laid out as follows:

vkcube.app
    Contents
        Frameworks
            libMoltenVK.dylib
            libvulkan.1.[version number].dylib
            libvulkan.1.dylib -> libvulkan.1.[version number].dylib
        Info.plist
        MacOS
            vkcube
        Resources
            VulkanIcon.icns
            Main.storyboardc
            vulkan
                icd.d
                    MoltenVK_icd.json
                explicit_layer
                    VkLayer_khronos_validation.json

Note: All required components are in the bundle. Signed apps will also have the _CodeSignature and CodeResources assets.

The layout on iOS and iPadOS is only slightly different:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "../../Frameworks/libMoltenVK.dylib",
        "api_version" : "1.2.0",
        "is_portability_driver": true
    }
}

Application Bundle Structure on iOS and iPadOS

The application bundle on iOS or iPadOS is only slightly different:

vkcube.app
    Frameworks
        libMoltenVK.dylib
        libvulkan.1.[version number].dylib
        libvulkan.1.dylib -> libvulkan.1.[version number].dylib
    Info.plist
    vkcube
    vulkan
        icd.d
            MoltenVK_icd.json
        explicit_layer.d
            VkLayer_khronos_validation.json

Next Steps

This guide provided an introduction to the main components and tools in the Vulkan SDK. Refer to the Vulkan SDK Download Site for the most up-to-date SDK information, including the complete set of SDK documentation.