Environment:Tencent Ncnn Vulkan Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, GPU_Compute |
| Last Updated | 2026-02-09 19:00 GMT |
Overview
Vulkan 1.0+ GPU compute environment with driver support and glslang for building and running ncnn with GPU acceleration on Windows, Linux, macOS, Android, and iOS.
Description
This environment provides the Vulkan GPU compute stack required by ncnn for hardware-accelerated neural network inference. ncnn includes its own minimal Vulkan loader (simplevk) that directly loads GPU vendor ICDs, eliminating the need for the full Vulkan SDK at runtime. At build time, glslang is required for compiling GLSL compute shaders to SPIR-V. The system supports a wide range of GPU vendors including NVIDIA, AMD, Intel, Qualcomm Adreno, ARM Mali, Apple (via MoltenVK), and Imagination PowerVR. ncnn maintains an internal blacklist for known buggy driver versions to ensure stability.
Usage
Use this environment for the Vulkan GPU Accelerated Inference workflow and any Implementation that requires `NCNN_VULKAN=ON`. This includes GPU instance creation, device detection, Vulkan compute pipeline execution, and GPU memory management. Required whenever `net.opt.use_vulkan_compute = true` is set at runtime.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, Windows, macOS (MoltenVK), Android (API 24+), iOS | Broad GPU platform support |
| GPU | Any Vulkan 1.0+ capable GPU | Discrete, integrated, or virtual GPU with compute queue |
| Vulkan API | >= 1.0.0 | 1.1 supported; auto-detected at runtime |
| GPU Driver | Vendor-specific Vulkan ICD | See Compatibility Notes for minimum versions |
| Disk | ~100MB | glslang + compiled shaders |
Dependencies
System Packages (Build Time)
- `glslang` (bundled as submodule, or system-installed with `-DNCNN_SYSTEM_GLSLANG=ON`)
- Vulkan headers (bundled via simplevk.h, no external Vulkan SDK required)
System Packages (Runtime)
- Vulkan ICD driver (vendor-specific):
- NVIDIA: nvoglv64.dll (Windows), libGLX_nvidia.so.0 (Linux)
- AMD: amdvlk64.dll (Windows), libvulkan_radeon.so (Linux)
- Intel: igvk64.dll (Windows), libvulkan_intel.so (Linux)
- Qualcomm: vulkan.adreno.so (Android)
- ARM Mali: libGLES_mali.so (Android), libMaliVulkan.so.1 (Linux)
- Apple: libMoltenVK.dylib (macOS/iOS)
Credentials
No credentials required.
Quick Install
# Build ncnn with Vulkan support
git clone https://github.com/Tencent/ncnn.git
cd ncnn
git submodule update --init
mkdir build && cd build
cmake -DNCNN_VULKAN=ON -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
# Python bindings with Vulkan
cd /path/to/ncnn
python setup.py install # Vulkan enabled by default in setup.py
Code Evidence
Vulkan API version detection from `src/gpu.cpp:2677-2688`:
uint32_t instance_api_version = VK_MAKE_VERSION(1, 0, 0);
PFN_vkEnumerateInstanceVersion vkEnumerateInstanceVersion =
(PFN_vkEnumerateInstanceVersion)vkGetInstanceProcAddr(0, "vkEnumerateInstanceVersion");
if (vkEnumerateInstanceVersion)
{
ret = vkEnumerateInstanceVersion(&instance_api_version);
if (ret != VK_SUCCESS)
{
NCNN_LOGE("vkEnumerateInstanceVersion failed %d", ret);
return -1;
}
}
Compute queue requirement from `src/gpu.cpp:518-594` (simplified):
// Search for dedicated compute queue first, then any compute queue
// If no compute queue found, device is rejected
Vulkan build flag from `CMakeLists.txt:81`:
option(NCNN_VULKAN "vulkan compute support" OFF)
Runtime Vulkan disabled by default from `src/option.cpp:33`:
use_vulkan_compute = false; // TODO enable me
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `no vulkan device` | No Vulkan-capable GPU found | Install or update GPU drivers with Vulkan support |
| `load vulkan driver failed` | Vulkan ICD not found | Install GPU vendor's Vulkan driver package |
| `vkCreateComputePipelines failed` | Buggy GPU driver | Upgrade GPU driver to latest version |
| `no compute queue` | GPU lacks compute queue capability | Use a different GPU or fall back to CPU inference |
| Tesla GPU not detected | Tesla uses TCC driver by default | Switch to WDDM driver mode (TCC lacks Vulkan support) |
Compatibility Notes
- Qualcomm Adreno: Driver API < 1.0.66 cannot share created pipelines. API < 1.1.87 has buffer2image dependency issues on some devices.
- ARM Mali: 16bit_storage is buggy in drivers with API < 1.0.82 (affects T760, T860, T880, G31, G51, G52, G71, G72, G76, G77).
- Vivante GC1700: 16bit_storage buggy in driver version 1.1.82.
- NVIDIA Tesla: Requires WDDM driver mode (not TCC) for Vulkan support.
- Android: Minimum API level 24 (Android 7.0). Devices with Android < 8.1 may have buggy blacklisted drivers.
- macOS/iOS: Uses MoltenVK to provide Vulkan over Metal. Supports VK_KHR_portability_subset.
- Platform Support Matrix: Windows (Intel/AMD/NVIDIA), Linux (Intel/AMD/NVIDIA/ARM), Android (Qualcomm/ARM), macOS (Intel/AMD/Apple), iOS (Apple).