<a class="site-logo" href="https://github.com/KhronosGroup/MoltenVK" title="MoltenVK"> <img src="Docs/images/MoltenVK-Logo-Banner.png" alt="MoltenVK" style="width:256px;height:auto"> </a>

MoltenVK

Copyright (c) 2015-2025 The Brenwill Workshop Ltd.

Table of Contents

• Introduction to MoltenVK
• Developing Vulkan Applications on macOS, iOS, tvOS, and visionOS
  • Using the Vulkan SDK
  • Using MoltenVK Directly
• Fetching MoltenVK Source Code
• Building MoltenVK
  • Building With Xcode
  • Building From the Command Line
  • Hiding Vulkan API Symbols
  • Accessing Metal Private API Calls
  • Install MoltenVK to Replace The Vulkan SDK libMoltenVK.dylib
• Running MoltenVK Demo Applications
• Using MoltenVK in Your Application
• MoltenVK and Vulkan Compliance
• Getting Support
• Contributing to MoltenVK Development

<a name="intro"></a> Introduction to MoltenVK

MoltenVK is a layered implementation of Vulkan 1.4 graphics and compute functionality, that is built on Apple's Metal graphics and compute framework on macOS, iOS, tvOS, and visionOS. MoltenVK allows you to use Vulkan graphics and compute functionality to develop modern, cross-platform, high-performance graphical games and applications, and to run them across many platforms, including macOS, iOS, tvOS, visionOS, Simulators, and Mac Catalyst, and all Apple architectures, including Apple Silicon.

Metal uses a different shading language, the Metal Shading Language (MSL), than Vulkan, which uses SPIR-V. MoltenVK automatically converts your SPIR-V shaders to their MSL equivalents.

To provide Vulkan capability to the macOS, iOS, tvOS, and visionOS platforms, MoltenVK uses Apple's publicly available API's, including Metal. MoltenVK does not use any private or undocumented API calls or features, so your app will be compatible with all standard distribution channels, including Apple's App Store.

The MoltenVK runtime package contains two products:

• MoltenVK is a implementation of an almost-complete subset of the Vulkan 1.4 graphics and compute API.

• MoltenVKShaderConverter converts SPIR-V shader code to Metal Shading Language (MSL) shader code. The converter is embedded in the MoltenVK runtime to automatically convert SPIR-V shaders to their MSL equivalents. In addition, the SPIR-V converter is packaged into a stand-alone command-line MoltenVKShaderConverter macOS tool for converting shaders at development time from the command line.

<a name="developing_vulkan"></a> Developing Vulkan Applications for macOS, iOS, tvOS, and visionOS

<a name="sdk"></a>

Using the Vulkan SDK

The recommended method for developing a Vulkan application for macOS is to use the Vulkan SDK.

The Vulkan SDK includes a MoltenVK runtime library for macOS. Vulkan is a layered architecture that allows applications to add additional functionality without modifying the application itself. The Validation Layers included in the Vulkan SDK are an essential debugging tool for application developers because they identify inappropriate use of the Vulkan API. If you are developing a Vulkan application for macOS, it is highly recommended that you use the Vulkan SDK and the MoltenVK library included in it. Refer to the Vulkan SDK Getting Started document for more info.

Because MoltenVK supports the VK_KHR_portability_subset extension, when using the Vulkan Loader from the Vulkan SDK to run MoltenVK on macOS, the Vulkan Loader will only include MoltenVK VkPhysicalDevices in the list returned by vkEnumeratePhysicalDevices() if the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR flag is enabled in vkCreateInstance(). See the description of the VK_KHR_portability_enumeration extension in the Vulkan specification for more information about the use of the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR flag.

<a name="download"></a>

Using MoltenVK Directly

If you are developing a Vulkan application for iOS, tvOS, or visionOS, or are developing a Vulkan application for macOS and want to use a different version or build of the MoltenVK runtime library than provided in the macOS Vulkan SDK, you can access a pre-built MoltenVK binary library from the MoltenVK repository, by selecting a repository commit from the list, and downloading the associated MoltenVK runtime library artifact.

Finally, if you want a customized build of MoltenVK, you can follow the instructions below to create a MoltenVK runtime library by fetching and building the MoltenVK source code.

To learn how to integrate the MoltenVK runtime library into a game or application, see the MoltenVK_Runtime_UserGuide.md document in the Docs directory.

<a name="install"></a> Fetching MoltenVK Source Code

To fetch MoltenVK source code, clone this MoltenVK repository, and then run the fetchDependencies script to retrieve and build several external open-source libraries on which MoltenVK relies:

1. Ensure you have cmake and python3 installed:

    brew install cmake
    brew install python3
   

   For faster dependency builds, you can also optionally install ninja:

    brew install ninja
   

2. Clone the MoltenVK repository:

    git clone https://github.com/KhronosGroup/MoltenVK.git
   

3. Retrieve and build the external libraries:

    cd MoltenVK
    ./fetchDependencies [platform...]
   

When running the fetchDependencies script, you must specify one or more platforms for which to build the external libraries. The platform choices include:

--all
--macos
--ios
--iossim
--maccat
--tvos
--tvossim

You can specify multiple of these selections. The result is a single XCFramework for each external dependency library, with each XCFramework containing binaries for each of the requested platforms.

The --all selection is the same as entering all of the other platform choices, and will result in a single XCFramework for each external dependency library, with each XCFramework containing binaries for all supported platforms and simulators.

Running fetchDependencies repeatedly with different platforms will accumulate targets in the XCFramework, if the --keep-cache option is used on each invocation.

For more information about the external open-source libraries used by MoltenVK, see the ExternalRevisions/README.md document.

<a name="building"></a> Building MoltenVK

During building, MoltenVK references the latest Apple SDK frameworks. To access these frameworks, and to avoid build errors, be sure to use the latest publicly available version of Xcode.

MoltenVK currently supports being built with Xcode 15.0.1 or later. Support is based on the earliest version of Xcode that can be verified in CI workflows.

Once built, the MoltenVK libraries can be run on macOS, iOS, tvOS, or visionOS devices that support Metal,or on the Xcode iOS Simulator, tvOS Simulator, or visionOS Simulator.

• The minimum runtime OS versions are indicated in the Deployment Target build settings in MoltenVK.xcodeproj.
• Information on macOS devices that are compatible with Metal can be found in this article.
• Information on iOS devices that are compatible with Metal can be found in this article.

<a name="xcode_build"></a>

Building With Xcode

The MoltenVKPackaging.xcodeproj Xcode project contains targets and schemes to build and package the entire MoltenVK runtime distribution package, or to build individual MoltenVK or MoltenVKShaderConverter components.

To build a MoltenVK runtime distribution package, suitable for testing and integrating into an app, open MoltenVKPackaging.xcodeproj in Xcode, and use one of the following Xcode Schemes, depending on whether you want a Release or Debug configuration, and whether you want to build for all platforms, or just one platform (in Release configuration):

• MoltenVK Package
• MoltenVK Package (Debug)
• MoltenVK Package (macOS only)
• MoltenVK Package (iOS only)
• MoltenVK Package (tvOS only)
• MoltenVK Package (visionOS only) (requires Xcode 15+)

Each of theseMoltenVKPackaging.xcodeproj Xcode project Schemes puts the resulting packages in the Package directory, creating it if necessary. This directory contains separate Release and Debug directories, holding the most recent Release and Debug builds, respectively.

Note: Due to technical limitations in t