Khronos Vulkan

Getting Started with the macOS Vulkan SDK

Creative Commons

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:

All documentation for the SDK can be found and downloaded online at 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.


Term Description
DXC Microsoft's Open Source DirectX Shader Compiler
ICD Installable Client Driver: A Vulkan-compatible display driver
GLSL OpenGL Shading Language
HLSL DirectX High-Level Shading Language
SPIR-V Standard Portable Intermediate Representation is a cross-API intermediate language (IL) that natively represents parallel compute and graphics programs
VMA The Vulkan Memory Allocator library provided by AMD
Vulkan Instance The Vulkan API object that stores all per-application states
Vulkan Layer A library designed to work as a plug-in for the loader. It usually serves to provide validation and debugging functionality to applications
Vulkan Loader A library which implements the Vulkan API entry points and manages layers, extensions, and drivers, shipped as part of MoltenVK and often shipped inside the application bundle of a Vulkan-based application (see below)


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, and tvOS platforms. It is NOT a fully-conforming Vulkan driver for macOS, iOS, 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 note that static linking is the only supported option currently for tvOS. Please see the MoltenVK Runtime User Guide on the MoltenVK GitHub for more information about MoltenVK specifics.

For desktop and iOS 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.

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

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:

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 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 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, 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:


Install the SDK

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

Installing is a simple operation involving mounting a disk image file and running the InstallVulkan application. If using Finder, navigate to the downloaded file and double-click the file to mount it. Once the dmg file is mounted double-click the InstallVulkan icon to start the installer. 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).

Optional Component Name Description
com.lunarg.vulkan.usr Copy loader, ICD, and tools into system wide /usr locations
com.lunarg.vulkan.sdl2 SDL2(both 32/64-bit) library
com.lunarg.vulkan.glm GLM (3D Math Library) headers
com.lunarg.vulkan.volk Volk (Vulkan Meta Loader) library
com.lunarg.vulkan.vma Vulkan Memory Allocator library
com.lunarg.vulkan.ios iOS support libraries
com.lunarg.vulkan.tvos tvOS version of MoltenVK.dylib

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 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 ./ --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, including all optional packages, you would use this command:

sudo ./ --root ~/VulkanSDK/ --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 com.lunarg.vulkan.tvos

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

sudo ./ --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 DLL's (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 availalbe 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 and To run these scripts, in your terminal navigate to the directory you installed the SDK files into and run:

sudo ./

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 Python3 (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 Python3.

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

sudo ./

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 ./ and do not just run ./ repeatedly copying the files over the previous versions.

Vulkan SDK contents

This section describes how the SDK contents are organized.

Directory Description
Applications Standalone Vulkan demos and tools
MoltenVK MoltenVK frameworks and libraries for macOS, iOS, and tvOS
macOS VULKAN_SDK tree; "System tree" with traditional bin, include, lib structure
macOS/bin Vulkan and shader tool executables
macOS/share/vulkan/explicit_layer.d Explicit layers that can be referenced with the VULKAN_LAYER_PATH environment variable
macOS/share/vulkan/icd.d MoltenVK ICD manifest JSON file for macOS
macOS/share/vulkan/registry Home of the vk.xml validusage.json and files
macOS/share/vulkan/config Home of the Vulkan Profiles .json files
macOS/Frameworks Vulkan loader framework for Xcode
macOS/include Vulkan and shader tool header files
macOS/lib Vulkan and shader tool libraries
iOS/share/vulkan/explicit_layer.d Explicit layers that can be included in iOS application bundles
iOS/share/vulkan/icd.d MoltenVK ICD manifest JSON file for iOS
iOS/lib Vulkan and shader tool libraries for iOS
tvOS/lib MoltenVK dynamic library for tvOS


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. Corresponding iOS and tvOS direcotories parallels this, but for iOS and tvOS 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 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:


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:


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


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:

$ vkvia
$ 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 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 devices. Layers however must be bundled with your application framework, and must be enabled programatically 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:

Layer Name Description
VK_LAYER_KHRONOS_validation Vulkan API validation and error checking.
VK_LAYER_LUNARG_api_dump Print API calls and their parameters and values.
VK_LAYER_KHRONOS_profiles Helps test across a wide range of hardware capabilities without physical access to every device.
VK_LAYER_KHRONOS_synchronization2 Implements the VK_KHR_synchronization2VK_KHR_synchronization2 extension, for use on systems without a driver that implements it.
VK_LAYER_KHRONOS_shader_object Implements the VK_EXT_shader_objectVK_EXT_shader_object extension, for use on systems without a driver that implements it.

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
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.


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.


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 and not required at all when using Vulkan Configurator to run your apps with validation layers.

Common Problems


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

Encountered "Could not start Vulkan Info" message in "Vulkan Info" tab of

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


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*>

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

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:


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


    "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 ( is laid out as follows:
            libvulkan.1.[version number].dylib
            libvulkan.1.dylib -> libvulkan.1.[version number].dylib

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

The layout on iOS is only slightly different: Modified:

    "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

The application bundle on iOS is only slightly different:
        libvulkan.1.[version number].dylib
        libvulkan.1.dylib -> libvulkan.1.[version number].dylib

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.