Install OpenCL Drivers on Debian Bookworm for GPU Acceleration

How to Install OpenCL

3. 3. Install Vendor OpenCL Drivers (Choose your GPU)

   Pick the vendor section matching your hardware and follow the commands.

   NVIDIA — use Debian non-free / backports or NVIDIA repo. Install the driver and OpenCL ICD packages:

   sudo apt install -y nvidia-driver

   sudo apt install -y nvidia-opencl-common

   sudo apt install -y nvidia-opencl-icd

   AMD (ROCm/OpenCL) — AMD provides Debian packages and an APT repository for ROCm and OpenCL runtime. Add the ROCm repo and install the packages suitable for Bookworm (follow AMD guidance for package selection):

   sudo apt update

   sudo apt install -y rocm-opencl-runtime

   Intel — Intel’s OpenCL ICD is packaged for Debian Bookworm as intel-opencl-icd (install the runtime package):

   sudo apt install -y intel-opencl-icd

4. 4. Verify the OpenCL Installation

   Confirm OpenCL platforms and devices are detected using clinfo.

   clinfo | grep -i opencl

   clinfo | grep -i device

   If clinfo runs but shows no devices, re-check driver installation, non-free repos (for NVIDIA), and kernel modules.

5. 5. Test GPU Acceleration

   Run clinfo to see the full platform/device details. You can also run a small OpenCL sample or benchmark to verify compute performance.

   clinfo

6. 6. Getting Started with OpenCL Programming

   Install development tools and headers to compile OpenCL examples:

   sudo apt install build-essential opencl-headers ocl-icd-opencl-dev

   Minimal compile/run flow:

   gcc -o hello_opencl hello_opencl.c -lOpenCL

   ./hello_opencl

   See the sample below for a minimal “Hello OpenCL” program you can paste and compile.

7. 7. Troubleshooting & Common Fixes

   • clinfo shows no platforms/devices: Ensure the ICD files for your vendor exist in /etc/OpenCL/vendors/ and that the vendor driver is installed and kernel modules are loaded.
   • NVIDIA issues: Confirm non-free repository or NVIDIA apt repo is enabled, blacklist nouveau if required, and that matching kernel headers are installed.
   • AMD/ROCm issues: ROCm may require specific kernel versions and packages; use AMD’s Debian guidance and their apt repository for Bookworm if available.
   • Intel issues: Check that the Intel ICD was built for your distro; some Intel packages require installing additional runtime components like Level Zero for newer stacks.
   • DKMS / Kernel mismatches: If driver DKMS modules fail to build, install the current kernel headers and re-run the DKMS build or use the distribution driver package matching your kernel.

8. 8. Expected clinfo Snippet (example)

   When properly installed, a short excerpt of clinfo output should include platform and device lines similar to:

   Platform Name: AMD ROCm
     Device Name: gfx1030 (Radeon RX 6700 XT)
   Platform Name: NVIDIA CUDA
     Device Name: NVIDIA GeForce RTX 3080
   Platform Name: Intel(R) OpenCL
     Device Name: Intel(R) UHD Graphics

   Exact names and device IDs will vary by hardware and driver version.

9. 9. Minimal “Hello OpenCL” C Example

   Save the snippet below as hello_opencl.c. It lists platforms and devices using the OpenCL API.

   #include <stdio.h>
   #include <stdlib.h>
   #include <CL/cl.h>
   
   int main(void) {
       cl_uint nPlatforms;
       cl_int status = clGetPlatformIDs(0, NULL, &nPlatforms);
       if (status != CL_SUCCESS || nPlatforms == 0) {
           printf("No OpenCL platforms found.\\n");
           return 1;
       }
       cl_platform_id *platforms = malloc(sizeof(cl_platform_id) * nPlatforms);
       clGetPlatformIDs(nPlatforms, platforms, NULL);
   
       for (cl_uint i = 0; i < nPlatforms; ++i) {
           char name[128];
           clGetPlatformInfo(platforms[i], CL_PLATFORM_NAME, sizeof(name), name, NULL);
           printf("Platform %u: %s\\n", i, name);
           cl_uint nDevices = 0;
           clGetDeviceIDs(platforms[i], CL_DEVICE_TYPE_ALL, 0, NULL, &nDevices);
           if (nDevices == 0) {
               printf("  No devices for this platform.\\n");
               continue;
           }
           cl_device_id *devices = malloc(sizeof(cl_device_id) * nDevices);
           clGetDeviceIDs(platforms[i], CL_DEVICE_TYPE_ALL, nDevices, devices, NULL);
           for (cl_uint d = 0; d < nDevices; ++d) {
               char dname[128];
               clGetDeviceInfo(devices[d], CL_DEVICE_NAME, sizeof(dname), dname, NULL);
               printf("  Device %u: %s\\n", d, dname);
           }
           free(devices);
       }
       free(platforms);
       return 0;
   }
       

   Compile and run:

   gcc -o hello_opencl hello_opencl.c -lOpenCL

   ./hello_opencl

10. 10. FAQ — Quick Answers

    • Q: clinfo runs but shows only ‘CPU’ or ‘mesa’ — where is my GPU?
      A: That means only a software/mesa ICD is active. Install the vendor ICD (NVIDIA, ROCm, or Intel package) and check /etc/OpenCL/vendors/.
    • Q: Can I install ROCm on Bookworm?
      A: AMD provides Debian support and an apt repository; follow AMD’s ROCm Debian instructions and use the ROCm packages built for Bookworm or the AMD repo as advised.
    • Q: Do I need non-free repositories?
      A: For NVIDIA proprietary drivers and some vendor binaries you will usually need Debian non-free or vendor repositories enabled.
    • Q: My DKMS module failed to build after kernel update — what now?
      A: Install matching kernel headers, re-run DKMS or reinstall the driver package compiled for your kernel.

11. 11. References & Further Reading

    • Debian packages and documentation for OpenCL ICDs and vendor runtimes.
    • AMD ROCm installation docs and Debian repository instructions.
    • Intel Compute Runtime packages for OpenCL on Debian.