Running apt install ocl-icd-opencl-dev, seeing no error, and assuming the GPU is now available to your transcoder is the single most common way an OpenCL setup goes wrong. The package installed. The runtime may or may not have. And the encoder will happily keep running on the CPU without telling you. That gap matters more for transcoding than for almost any other GPU workload, because a transcoding fleet is something you pay for by the hour and measure by the stream. If the OpenCL runtime is not correctly installed, discoverable, and matched to your driver stack, the encoder does not crash — it falls back to CPU. The pipeline still produces valid output. The only visible symptom is a cost-per-stream number that is quietly two to five times higher than it should be, and that regression looks like a code problem three sprints later when nobody is looking at the install. What “install OpenCL” actually means in practice The phrase hides three separate components that people conflate into one apt line. Installing OpenCL is not one action; it is confirming that three pieces exist and agree with each other. The first is the ICD loader — the Installable Client Driver mechanism. On Linux this is usually ocl-icd (the package ocl-icd-libopencl1 provides libOpenCL.so). The loader is vendor-neutral. It does not talk to any GPU. Its only job is to read the files in /etc/OpenCL/vendors/ and dispatch your application’s OpenCL calls to whichever real runtime those files point at. Installing the loader gives you a working libOpenCL.so and exactly zero devices. The second is the runtime — the vendor’s actual OpenCL implementation, the thing that turns OpenCL calls into work on real silicon. For NVIDIA this ships inside the driver package. For AMD it is part of ROCm or the AMDGPU-PRO stack. For Intel it is the compute-runtime (intel-opencl-icd). The runtime drops an ICD file into /etc/OpenCL/vendors/ that points the loader at itself. No ICD file, no device — even if the driver is loaded and the GPU is visible to the kernel. The third is the GPU driver — the kernel module and userspace that let the OS use the card at all (nvidia.ko, amdgpu, i915/xe). The driver being loaded is necessary but not sufficient; a machine can have a perfectly working driver, a GPU visible in nvidia-smi or lspci, and still enumerate zero OpenCL devices because the runtime’s ICD registration is missing or version-mismatched. The failure mode we see most often in the field is a loader present, a driver present, and a runtime either absent or mismatched — so clinfo reports “Number of platforms: 0” while every other GPU tool looks healthy. That is the divergence point the whole install turns on: a setup that survives a device-enumeration check gives you a transcoding fleet you can profile and cost, and a setup that “runs” but silently falls back to CPU gives you a cost regression disguised as an application bug. Why the three-layer split matters for transcoding specifically Video transcoding is unusual among GPU workloads in how gracefully it degrades. A CUDA training job that loses its device errors out immediately. A transcoder built on a framework like FFmpeg with an OpenCL filter, or an encoder library that offloads scaling and colour conversion to OpenCL, does not error out — it falls through to a CPU code path that produces byte-for-byte comparable output. That resilience is the trap. Because the output is correct, nothing downstream flags the fallback. The stream plays. Quality metrics pass. The only thing that changes is where the compute happened, and that only shows up in the metric almost nobody watches at install time: GPU utilisation. This is why a verified OpenCL install is the precondition for measuring GPU utilisation across a transcoding fleet — the number the cost-per-stream lever depends on. If you cannot trust that the encoder is dispatching to the GPU, your utilisation reading is meaningless and every optimisation decision built on top of it is built on sand. It is worth being precise about scope here. OpenCL is one of several ways a transcoder touches the GPU, and for many pipelines it is not the encode path itself — dedicated hardware blocks like NVENC, VA-API, or Intel Quick Sync handle the actual entropy coding, while OpenCL handles the general-compute stages around it: scaling, deinterlacing, colour-space conversion, overlay compositing. If your bottleneck is the encoder itself, the reasoning in our explainer on how H.265 encoding cuts bitrate at a held quality target is the relevant lever, not the OpenCL filter chain. Get the OpenCL install right so that the filter stages are on the GPU where you intended them; then reason about the encoder separately. How do you install OpenCL for NVIDIA, AMD, and Intel GPUs? The loader is common across all three vendors; the runtime differs. Install the vendor-neutral loader once, then add exactly one vendor runtime. The table below is the decision surface — it maps each vendor to the runtime package that registers the ICD, and names the file that must appear in /etc/OpenCL/vendors/ for enumeration to succeed. Vendor ICD loader (common) Runtime package Registers ICD file Notes NVIDIA ocl-icd-libopencl1 ships inside the NVIDIA driver nvidia.icd Runtime version tracks the driver; no separate OpenCL package to install AMD ocl-icd-libopencl1 ROCm (rocm-opencl-runtime) or AMDGPU-PRO amdocl64.icd (or similar) ROCm gates on specific kernel and card generations — check the support matrix Intel ocl-icd-libopencl1 intel-opencl-icd (compute-runtime) intel.icd Newer xe/i915 stack; version must match the compute-runtime release Two rules cut across every row. First, install the loader from the distribution, not from the vendor, and let the vendor runtime register itself — mixing a vendor-shipped libOpenCL.so with the distro loader is a frequent source of the “zero platforms” symptom. Second, the runtime version is not free to float. On NVIDIA the OpenCL runtime is welded to the driver version, so a driver upgrade that outpaces your CUDA/runtime expectations can change enumeration behaviour. On Intel and AMD the compute-runtime or ROCm release must match a supported kernel and card generation, and installing the newest package on an unsupported kernel produces a loader that finds the ICD file but a runtime that enumerates nothing. If your deployment target is Ubuntu specifically, the vendor-neutral mechanics above are the same, but the exact package names and repository setup have their own footguns — our walkthrough on installing OpenCL on Ubuntu for GPU video-analytics workloads covers the distribution-level detail this hub deliberately keeps vendor-general. For pipelines that run partly on CPU and need a fallback path that is intentional rather than accidental, POCL — portable OpenCL is the runtime that makes the CPU path a choice you can measure. How do you verify OpenCL enumerates the GPU rather than falling back to CPU? Verification is not optional and it is not the same thing as “no install error”. The install can succeed and the enumeration can still be empty. Run this sequence before you trust any utilisation number. Confirm the loader sees at least one platform. Run clinfo. “Number of platforms: 0” means the loader found no ICD file — the runtime is not registered. This is the most common stopping point. Confirm the intended device is enumerated, by name. In clinfo output, check Device Name and Device Type. You want to see your actual GPU (e.g. an NVIDIA, AMD, or Intel device) with Device Type: CL_DEVICE_TYPE_GPU. If the only device is a CPU, or a software runtime like POCL you did not intend, you have a fallback, not a GPU install. Confirm the ICD file exists and points at the right runtime. List /etc/OpenCL/vendors/. There should be one .icd file per intended vendor, each containing the path to that vendor’s runtime .so. A stale file pointing at an uninstalled runtime is a classic post-upgrade break. Confirm the transcoder dispatches to the GPU under load. Start a representative transcode with the OpenCL filter chain enabled and watch nvidia-smi (or radeontop, or intel_gpu_top) for non-trivial GPU utilisation. Zero GPU activity while the transcode runs is the definitive sign of silent CPU fallback. Record a baseline GPU utilisation reading. Before any optimisation, capture utilisation under a known stream count. This is the number the cost-per-stream analysis is built on, and it only means anything once steps 1–4 pass. The discipline here is observed-pattern guidance drawn from setup work across transcoding engagements, not a benchmarked threshold — the exact utilisation you should expect depends entirely on codec, resolution, and how much of the pipeline is on the OpenCL filter path versus the fixed-function encoder. The point is not a target number; it is that a baseline captured before verification is a baseline you cannot trust. What version-mismatch and fallback problems most commonly break a transcoding setup? Three patterns account for most of the “it was working, now it enumerates nothing” tickets we see. First, a driver upgrade that outpaces the runtime registration — the new driver ships, the old .icd file is stale, and the loader dispatches to a runtime that no longer exists. Second, a mismatched compute-runtime and kernel on Intel or AMD, where the newest package installs cleanly but silently declines to enumerate on an unsupported kernel or card generation. Third, two loaders on the same box — a vendor-shipped libOpenCL.so shadowing the distro ocl-icd loader, so which one your application links against depends on library path ordering, which is not something you want deciding whether your fleet uses its GPUs. All three share a signature: no crash, a plausible-looking install, and an enumeration that quietly comes up short. That is why the verification sequence above ends at “watch the GPU under load” rather than “the package installed”. The install is a claim; enumeration under load is the evidence. FAQ How does installing OpenCL actually work? Installing OpenCL means putting three cooperating pieces in place: a vendor-neutral ICD loader (libOpenCL.so), a vendor runtime that does the real GPU work, and the GPU driver that lets the OS use the card. In practice the loader dispatches your OpenCL calls to whichever runtime is registered in /etc/OpenCL/vendors/, so “installed” only means something once the runtime has registered its ICD file and a device actually enumerates. What is the difference between the OpenCL ICD loader, the runtime, and the GPU driver, and why do you need all three? The ICD loader is vendor-neutral plumbing that routes calls but touches no hardware. The runtime is the vendor’s implementation that turns OpenCL calls into GPU work and registers itself with the loader. The driver is the kernel-level component that lets the OS use the card at all. You need all three because each is necessary and none is sufficient alone — a loaded driver with no registered runtime still enumerates zero OpenCL devices. How do you install OpenCL for NVIDIA, AMD, and Intel GPUs, and where do the packages differ? Install the common distro loader (ocl-icd-libopencl1) once, then add exactly one vendor runtime. NVIDIA ships its runtime inside the driver; AMD uses ROCm or AMDGPU-PRO; Intel uses intel-opencl-icd. The packages differ mainly in which runtime registers the ICD file and how tightly the runtime version is bound to the driver, kernel, and card generation. How do you verify that OpenCL enumerates the intended GPU rather than falling back to CPU? Run clinfo and confirm at least one platform, then check that the enumerated Device Name is your GPU with Device Type: CL_DEVICE_TYPE_GPU. Confirm the .icd file in /etc/OpenCL/vendors/ points at a real runtime, then start a representative transcode and watch nvidia-smi (or the vendor equivalent) for non-trivial GPU utilisation. Zero GPU activity under load means silent CPU fallback. Why does OpenCL matter for a GPU video transcoding pipeline specifically? Because transcoding degrades gracefully: if OpenCL is misconfigured, the encoder falls back to CPU and still produces correct output, so nothing downstream flags the problem. The only symptom is inflated cost-per-stream and low GPU utilisation. A verified OpenCL install is the precondition for trusting the utilisation metric that every cost-per-stream decision depends on. What version-mismatch and fallback problems most commonly break an OpenCL transcoding setup? Three patterns dominate: a driver upgrade that leaves a stale ICD file pointing at a removed runtime; a compute-runtime or ROCm release that mismatches the kernel or card generation and enumerates nothing on install; and two competing loaders on one box where library path ordering decides which runtime wins. All three share the same signature — no crash, a plausible install, and an enumeration that quietly comes up empty. Where this leaves the fleet A correct OpenCL install is not the interesting part of a transcoding project. It is the boring precondition that determines whether the interesting parts — profiling GPU utilisation, naming the cost-per-stream lever, deciding where the encoder should run — are built on measurable ground or on a silent CPU fallback. If you are standing up a fleet on our media and telecom broadcast work, the enumeration check comes before the optimisation, not after the cost regression. The failure class to name in the runbook is silent CPU fallback on a plausible install, and the artifact that catches it is a device-enumeration-under-load check run before any baseline utilisation reading is recorded.
