Getting started#

Prerequisites#

  • A Vulkan 1.2 driver. lavapipe, Mesa’s CPU implementation, is enough to try it without a GPU.

  • Python 3.11 or newer.

  • libclc’s clspv--.bc, from LLVM 22 or older, for accurate and double-precision math (see The math library). Without it, float64 math functions are unavailable.

  • Optional: spirv-val from SPIRV-Tools, to validate generated shaders.

Installation#

From PyPI#

Install the Vulkan loader (libvulkan1 on Debian and Ubuntu, vulkan-loader on Fedora and Arch) and a driver for your GPU, then:

pip install numba-vulkan        # or: uv add numba-vulkan

The wheel contains libclc, so accurate and float64 math work without further setup. On macOS, install MoltenVK and an llc of LLVM 22 as described under macOS below; NUMBA_VULKAN_LLC must name the llc. Checking the setup shows how to see which devices numba-vulkan finds.

The sections that follow set up a source checkout, for working on numba-vulkan itself.

With devenv#

On NixOS, or any system with Nix, the devenv shell provides Python, uv, the Vulkan loader, libclc, SPIRV-Tools and vulkaninfo. GPU drivers come from the host.

devenv shell
uv run pytest

Without Nix#

Install the Vulkan loader (libvulkan1 on Debian and Ubuntu, vulkan-loader on Fedora and Arch) and a driver for your GPU. Wheels contain libclc. When working from a source checkout instead, install your distribution’s libclc package or point NUMBA_VULKAN_LIBCLC at clspv--.bc. Then:

uv sync
uv run pytest

macOS#

On macOS, Vulkan runs on top of Metal through MoltenVK. numba-vulkan asks the Vulkan loader for such “portability” drivers and enables what they need. The test suite passes on an Apple M3 Pro with MoltenVK 1.4.2.

llvmlite’s SPIR-V backend crashes on macOS arm64 (KI-32 in Known issues), so numba-vulkan needs an llc of LLVM 22 there, named by NUMBA_VULKAN_LLC. The devenv shell provides it, together with MoltenVK, the Vulkan loader and libclc, and sets the environment variables that find them; this is the tested setup:

devenv shell -- uv run pytest

Without Nix, Homebrew provides the same parts. This way has not been tested:

brew install molten-vk vulkan-loader vulkan-tools
# Homebrew on Apple silicon installs into /opt/homebrew/lib, where the
# `vulkan` Python package does not look by itself:
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
# An llc of LLVM 22, the version inside llvmlite, from wherever it is installed:
export NUMBA_VULKAN_LLC=/path/to/llvm-22/bin/llc
vulkaninfo --summary       # should list the GPU with the MoltenVK driver
uv sync
make libclc                # optional: accurate float32 math (see below)
uv run python -c "import numba_vulkan as nv; print(nv.list_devices())"

If vulkaninfo lists no device, point the loader at MoltenVK’s manifest with export VK_DRIVER_FILES=/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json (or the share/vulkan/icd.d directory, depending on the version). The LunarG Vulkan SDK is an alternative to Homebrew.

Apple GPUs have no float64 (Metal does not offer it), so kernels compute float64 values in float32 and warn about it (see Limitations). make libclc puts libclc into the source checkout; it downloads conda-forge’s package unless Nix is installed, and the file is the same on every platform. Without it, float32 math uses the driver’s functions. CUDA does not exist on macOS, so the benchmarks leave out numba-cuda.

Windows#

GPU drivers on Windows come with the Vulkan loader, so pip install numba-vulkan is all it takes. The test suite runs on Windows with Mesa’s lavapipe before every release (.github/workflows/windows.yml), and the benchmarks have run on an Intel Arc GPU. Windows has no fork, so each kernel’s first compilation starts a process of its own and takes a little longer than on Linux or macOS.

Checking the setup#

import numba_vulkan as nv

nv.list_devices()
# [<0: NVIDIA TITAN X (Pascal) (discrete)>,
#  <1: Intel(R) UHD Graphics 630 (CFL GT2) (integrated)>,
#  <2: llvmpipe (LLVM 21.1.8, 256 bits) (cpu)>]

The test suite runs every test on every device in that list and validates each generated shader with spirv-val when it is installed. The tests and examples are part of the repository, not of the package installed from PyPI, so they run in a copy of it: a git clone, or the zip of main from GitHub.

git clone https://github.com/arunoruto/numba-vulkan
cd numba-vulkan
uv run pytest
uv run python examples/saxpy.py

Building this documentation#

uv sync --group docs
cd docs
uv run sphinx-build -M html ./source ./build