The SPIRV-LLVM-Translator converts between LLVM IR and compute SPIR-V

A translator restricted to the compute flavour

The SPIRV-LLVM-Translator is a tool and a library for bi-directional translation between SPIR-V and LLVM IR, and the scope limit is stated in the second paragraph of the documentation. The project currently only supports the OpenCL and compute flavour of SPIR-V, consuming and producing SPIR-V modules that declare the `Kernel` capability. That single sentence decides whether the project is relevant to you, because a graphics shader that declares different capabilities is outside what this translator handles. The directory structure shows how the work is split. The public interface is the header `include/LLVMSPIRVLib.h`, `lib/SPIRV` holds the library for the SPIR-V in-memory representation along with the decoder, the encoder and the translator itself, and `tools/llvm-spirv` is the command line utility for translating between LLVM bitcode and SPIR-V binary. The repository is a Khronos project with a `CODE_OF_CONDUCT.md`, a `CONTRIBUTING.md`, a `LICENSE.TXT` and a `LLVMSPIRVLib.pc.in` file for pkg-config.

Three ways to build it

The build instructions cover three situations, and the choice is mostly about where your LLVM comes from. The `main` branch of the repository is aimed to be buildable with the latest LLVM `main` revision. If you want a pre-installed LLVM, Ubuntu and Debian have nightly repositories at apt.llvm.org, and the documentation shows the pattern for adding the key and the repository and installing the development packages:

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo add-apt-repository "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial main"
sudo apt-get update
sudo apt-get install llvm-24-dev llvm-24-tools clang-24 libclang-24-dev

If you have your own LLVM build, the same three step shape applies with a different cmake invocation:

git clone https://github.com/KhronosGroup/SPIRV-LLVM-Translator.git
mkdir SPIRV-LLVM-Translator/build && cd SPIRV-LLVM-Translator/build
cmake .. -DLLVM_DIR=<llvm_build_dir>/lib/cmake/llvm/
make llvm-spirv -j`nproc`

When the translator is consumed by another CMake project rather than built standalone, the documentation says you need to define `LLVM_SPIRV_BUILD_EXTERNAL`.

Building inside the LLVM tree

The third option is to make the translator a regular LLVM subproject, which is how it is built in the LLVM project itself. The repository is cloned into the `llvm/projects` or the `llvm/tools` directory, and then cmake is run for LLVM as usual, after which the `llvm-spirv` and `check-llvm-spirv` targets exist:

git clone https://github.com/llvm/llvm-project.git
cd llvm-project/llvm/projects
git clone https://github.com/KhronosGroup/SPIRV-LLVM-Translator.git

The interesting wrinkle is the dependency on clang. There are tests in the translator that depend on the `clang` binary, which makes clang a required dependency for the `check-llvm-spirv` target, and the documentation points at `LLVM_SPIRV_TEST_DEPS` in `test/CMakeLists.txt` for the details. Building clang from sources takes time and resources, and there are two documented ways around it. If you do not want to run the unit tests at all, you can pass `-DLLVM_SPIRV_INCLUDE_TESTS=OFF` to disable the generation of test targets. If you do want the tests but not clang, `-DSPIRV_SKIP_CLANG_BUILD` avoids adding clang as a dependency, although LIT will still look for the clang binary when the tests are launched. Building and testing completely without clang is not supported at the moment, and issue 477 is where that is tracked.

SPIRV-Tools for readable assembly and validation

The translator can optionally lean on SPIRV-Tools, and the two features it adds are practical ones. The first is generating assembly with widely adopted syntax rather than the raw numeric form, and the second is validating SPIR-V before a reverse translation. Both are enabled with cmake options, `-DLLVM_SPIRV_ENABLE_LIBSPIRV_DIS=ON` for the disassembly side and `-DLLVM_SPIRV_ENABLE_LIBSPIRV_VAL=ON` for the validation side. If SPIRV-Tools were installed before the build they are detected automatically, and otherwise pkg-config is pointed at the installation with `PKG_CONFIG_PATH` set to the tools' `lib/pkgconfig/` directory before the cmake invocation. The documentation also shows how to verify the integration, by asking the tool to disassemble a bitcode file:

llvm-spirv --spirv-tools-dis input.bc -o -

The expected result is that the output is printed in the standard assembly syntax. For a project that cares about whether a module is valid before it is consumed, that validation step is the reason to turn the option on rather than leaving it off.

The spirv.hpp header is a separate dependency

One dependency is easy to miss because it is not a library but a header file. The translator build depends on the official Khronos header `spirv.hpp`, which maps SPIR-V extensions, decorations and instructions onto numeric tokens, and the official version is published in the KhronosGroup SPIRV-Headers repository. There are three documented ways to get it. By default the header repository is downloaded from the Khronos Group GitHub and placed into `<build_dir>/SPIRV-Headers`. If you build the translator in tree, you can download the SPIRV-Headers repository manually into `llvm/projects`, where the LLVM build scripts will pick it up, and the folder has to keep its default name. Any build type can also use an external installation of the headers, which is the option to reach for when your build environment has no network access to GitHub or when you need to pin a specific header revision, something the `spirv-headers-tag.conf` file at the repository root is there to support.

Release branches track LLVM versions

The release history shows the versioning model, which follows LLVM rather than the calendar. The three most recent tags are v21.1.12, v22.1.7 and v23.1.2, all published on 2026-10-01, and each is described as the SPIR-V LLVM translator based on a specific LLVM version, 21.1, 22.1 and 23.1 respectively. So when you pick a tag, you are picking the LLVM line it was made for, and the practical rule is to take the branch that matches the LLVM your toolchain already uses rather than the newest tag. The `main` branch tracks LLVM `main` and is where new work lands, which is what the scheduled CI badges at the top of the documentation refer to, with separate workflows for the out-of-tree build and tests and for the in-tree build and tests. The last push to the repository was on 2026-10-19 and the repository is not archived, so the LLVM main line is where the fixes for a new LLVM release will appear first. The licence is the one in LICENSE.TXT, and the documentation states the software may be freely distributed under the terms of that agreement, while the project listing classifies it as a custom licence.

Editorial conclusion

Engineers working on compute toolchains who need to move between LLVM IR and SPIR-V will find this the reference implementation, with both a library, LLVMSPIRVLib, and the llvm-spirv command line tool, and with release branches tracked against LLVM 21, 22 and 23. It is the wrong tool for graphics or general purpose SPIR-V, because the documentation states it supports only the OpenCL and compute flavour, and it is the wrong tool if you cannot provide a matching LLVM, since the main branch targets LLVM main. Before you build it, decide whether you need the SPIRV-Tools integration and the clang-based test suite, because both change the shape of the build.

Frequently asked questions

Official sources

1. Issues
2. KhronosGroup/SPIRV-LLVM-Translator on GitHub
3. README
4. Releases