Vulkan-Headers is a staging area for the headers the Vulkan SDK ships

A staging area, which is an unusual thing for a repository to be

Vulkan-Headers is described as Vulkan header files and API registry, and it contains Vulkan header files, include files for C and C++, and related scripts and tests. That description is accurate and it is also incomplete in an important way.

Most of the files in the repository are sourced from, or generated from, other repositories, as described in CONTRIBUTING.md. And then the sentence that explains the whole thing: Vulkan-Headers exists as a staging area for these files, most of which are then consumed by downstream repositories used to build SDK components such as the Vulkan Validation Layers and Conformance Test Suite.

So this repository is a transit point, not the origin. Files arrive here from elsewhere, and they leave here into the projects that ship them to developers. It is the shape of a distribution pipeline rather than the shape of a library, and that changes how you should think about depending on it.

The homepage is vulkan.org, and the copyright notice in the file header is The Khronos Group Inc. The last push was on 2026-10-02, the project is not archived, and the repository has no GitHub releases, which is consistent with a repository whose release history lives in tags and in the SDK rather than in GitHub release entries.

include, registry and tests are the three things in the tree

The top level of the repository is short enough to read in one go, and it maps onto the three roles the project plays.

The include/ directory is the header set itself, the C and C++ include files that a program compiles against. The registry/ directory holds the API registry, which is the machine readable description of the Vulkan API: its types, its commands, its extensions and the enumerants that go with them. The tests/ directory holds tests for the repository's contents.

Around those sit the build and governance files. There is a CMakeLists.txt and a BUILD.gn for the GN build system, so the headers can be consumed by either CMake or GN projects, and a Makefile.release. The governance layer is notable for a project of this size: a CODE_OF_CONDUCT.adoc, a SECURITY.md, a CONTRIBUTING.md and a BUILD.md.

Two files there are worth calling out specifically. REUSE.toml is the metadata file for REUSE compliance, the standard practice of recording every file's licence and copyright in a machine readable way, and it pairs with the LICENSES/ directory. The presence of both tells you that the repository is carefully accounted for at the level of individual files, which is what you would expect from a project that aggregates content from many upstream sources and then redistributes it.

The practical point for a consumer is that the registry is the interesting artefact if you are not just compiling against the API. A tool that generates bindings, or a project that needs to know which extensions exist in a given spec version, wants the registry rather than the headers.

Where developers are supposed to get the headers

The README is unusually direct about this, and it is the part of the file that saves you time.

Developers normally obtain headers from the official Vulkan-SDK. They can also use headers from, or packaged from, this repository. In most cases, developers should only need the headers, not the scripts and other material in this repository. And if you need to run the scripts, you should use them from their canonical source in the Vulkan Specification repository, Vulkan-Docs.

That last point is the one that catches people. The scripts in this repository are present because the files are staged here, not because they are meant to be run from here. Running them from a checkout of Vulkan-Headers is using a copy in the wrong place, and the README tells you to go to the source instead.

There is also a third route, which the README lists under package manager support. Vulkan-Headers are supported by both conan and vcpkg, so a project that already uses one of those can pull the headers in as a dependency rather than vendoring them or installing the full SDK.

That gives three options with a clear order of preference for most teams. The SDK is the tested, complete distribution and is what the README points you to. A package manager is the right choice when the dependency graph is already managed that way. And this repository itself is for people who need the registry, need the scripts, or are working on the toolchain itself.

Two tag formats, and the difference between them is a testing level

The version tagging scheme section is short and easy to miss, and it is the part that matters most if you pin a dependency.

Updates to this repository that correspond to a new Vulkan specification release are tagged using the format v<version>, with v1.3.266 given as the example. The note that follows is the important sentence: marked version releases have undergone thorough testing but do not imply the same quality level as SDK tags. SDK tags follow the vulkan-sdk-<version>.<patch> format, with vulkan-sdk-1.3.266.0 as the example. The scheme was adopted following the 1.3.266 Vulkan specification release.

So the two numbering schemes are not two branches of the same thing, they are two levels of assurance. A v1.3.266 tag is the headers as the specification defines them. A vulkan-sdk-1.3.266.0 tag is the same headers as they were tested and shipped inside an SDK build.

For a project that pins the headers, that difference is the whole decision. If you are reproducing a bug against a specific spec revision, the v tag is what you want, because it is the exact content of the specification release. If you are shipping a product, the SDK tag is the one that has been through the validation and conformance tooling.

The version in the tag is the Vulkan specification release the headers correspond to. That is the same structure the whole Vulkan ecosystem uses, so the tag here lines up with the loader and the layers you already have.

Apache 2.0 in the file headers, and a licence the repository manages

The licence needs a small clarification, because there are two things in the repository and they are not the same thing.

The copyright header at the top of the README, and the SPDX identifier that goes with it, is Apache-2.0, Copyright 2018-2023 The Khronos Group Inc. That is the licence applied to the README file itself.

At the same time, the repository's own licence status is not one of the standard ones that GitHub can classify, and the files in the tree are LICENSE.md and a LICENSES/ directory, with REUSE.toml tying them together. The REUSE model is the answer to a problem that a repository like this has: the content is aggregated from many upstream projects, and each of those upstream projects has its own licence and attribution requirements. A single LICENSE file cannot express that, so the licences are stored per file and indexed in a machine readable manifest.

The practical consequence is that if you vendor files from here into a product, you are picking up the licences of the individual upstream sources as well, and the REUSE.toml and LICENSES/ directory are how you find out what applies to what. The scripts in particular come from the Vulkan-Docs repository, and they carry their own terms.

The homepage for the wider effort is vulkan.org, the SDK that ships these headers is at lunarg.com, and the header repository itself is on GitHub under KhronosGroup.

Editorial conclusion

Use Vulkan-Headers directly if you need the registry, if you are building something that generates code from it, or if you are contributing to the Khronos toolchain. Otherwise take the headers from the official Vulkan-SDK or from conan and vcpkg, because the SDK is the tested distribution and the tag naming in this repository says so explicitly. Verify first which spec version you need, because the v1.3.266 style tags and the vulkan-sdk-1.3.266.0 style tags carry a different level of testing, and the README says as much.

Frequently asked questions

Official sources

1. Issues
2. KhronosGroup/Vulkan-Headers on GitHub
3. Project website
4. README