PyOpenCL

Common errors

• ImportError: DLL load failed: The specified procedure could not be found.

  cause This error typically occurs on Windows when a required native OpenCL DLL or one of its dependencies cannot be found or is incompatible with the PyOpenCL wheel installed. This often happens due to a mismatch between the OpenCL version PyOpenCL expects and what's available on the system, or issues with environment variables (PATH, INCLUDE, LIB).
  fix Verify that your OpenCL SDK/drivers are correctly installed and up-to-date for your hardware. If installing wheels, ensure it matches your Python version and the OpenCL version supported by your drivers (e.g., `+cl12` for OpenCL 1.2). Sometimes, explicitly setting `INCLUDE` and `LIB` environment variables for your OpenCL SDK path before `pip install pyopencl --no-cache-dir` can resolve this.

• pyopencl.LogicError: clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR

  cause PyOpenCL installed successfully, but it cannot find any OpenCL platforms (i.e., no OpenCL drivers/ICDs are installed or properly configured on the system).
  fix Install the appropriate OpenCL drivers for your GPU (NVIDIA CUDA Toolkit, AMD Radeon Software, Intel Graphics Drivers) or a CPU-based OpenCL implementation like `poclo` (`pip install poclo`). Ensure system environment variables or ICD files (`.icd`) correctly point to the installed OpenCL runtime.

• pyopencl.RuntimeError: clBuildProgram failed: invalid build options

  cause The OpenCL kernel program failed to compile, often due to invalid compiler flags passed during `Program.build()` or syntax errors within the OpenCL C kernel code itself. This can also happen if the OpenCL version requested in the program is not supported by the device.
  fix Inspect the build log for detailed error messages (set `PYOPENCL_COMPILER_OUTPUT=1` environment variable). Correct any syntax errors in the OpenCL kernel. Ensure build options are valid for your OpenCL device and version.

• pyopencl.LogicError: clEnqueueNDRangeKernel failed: invalid work item size

  cause This error typically occurs when the `global_size` or `local_size` arguments passed to a kernel enqueue call (`prg.kernel_name(queue, global_size, local_size, ...)`) are invalid or incompatible with the device's capabilities. Common issues include `global_size` not being divisible by `local_size`, or `local_size` exceeding device limits.
  fix Ensure `global_size` is a multiple of `local_size` for each dimension. Query `device.max_work_group_size` and `device.max_work_item_sizes` to set appropriate `local_size` values. For simple cases, passing `None` for `local_size` lets the OpenCL driver choose an optimal value.

Warnings

• breaking The `Event.profile` attributes for profiling information were deprecated in `v2025.2.5` in favor of lower-case attributes (e.g., `evt.profile.end` instead of `evt.profile.END`).
  Fix: Update code to use lower-case attribute names for `Event.profile` access (e.g., `event.profile.end`).
• gotcha PyOpenCL requires an installed OpenCL Installable Client Driver (ICD) to access hardware. Without it, `cl.create_some_context()` or similar calls will raise a `pyopencl.LogicError: clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR`.
  Fix: Install vendor-specific OpenCL drivers (e.g., from NVIDIA, AMD, Intel) for your hardware. For CPU-only OpenCL, `poclo` can be installed via pip. Ensure the OpenCL runtime is correctly configured for your system.
• gotcha Mixing PyOpenCL installations from `pip` with OpenCL ICDs/runtimes from `conda-forge` can lead to issues with the ICD loader, potentially preventing access to system-wide OpenCL devices.
  Fix: Avoid mixing installation sources. If using `conda`, install both PyOpenCL and relevant OpenCL runtimes (like `poclo` or vendor-specific packages) from `conda-forge`. If using `pip`, ensure your OpenCL drivers are system-wide installations.
• gotcha Direct kernel invocation via `prg.kernel_name(queue, global_size, local_size, *args)` is not thread-safe, as it internally sets arguments before enqueuing. Concurrent calls from multiple threads can lead to race conditions.
  Fix: For thread-safe kernel execution, create a separate kernel object for each thread that will enqueue calls, or use appropriate locking mechanisms.
• deprecated Many older buffer transfer functions (e.g., `cl.enqueue_write_buffer`, `cl.enqueue_read_buffer`) have been deprecated in favor of `cl.enqueue_copy` for improved flexibility and efficiency.
  Fix: Use `cl.enqueue_copy(queue, dest, src)` for all data transfers between host and device or between device buffers.

Install

• pip install pyopencl Install PyOpenCL

Imports

• cl

  import pyopencl as cl

• array

  import pyopencl.array as cla

  Common alias for convenience when working with GPU arrays.

Quickstart

This quickstart demonstrates a basic PyOpenCL workflow: creating an OpenCL context and command queue, preparing data on the host (NumPy array), transferring it to the device, compiling and executing a simple OpenCL kernel (doubling array elements), and transferring results back to the host.

import pyopencl as cl
import numpy as np

def run_opencl_kernel():
    # 1. Create a context
    try:
        ctx = cl.create_some_context()
    except cl.LogicError as e:
        print(f"Error creating OpenCL context: {e}")
        print("Please ensure you have OpenCL drivers/ICD installed.")
        return

    # 2. Create a command queue
    queue = cl.CommandQueue(ctx)

    # 3. Prepare host data
    a = np.random.rand(50000).astype(np.float32)

    # 4. Create device buffers and transfer data
    mf = cl.mem_flags
    a_buf = cl.Buffer(ctx, mf.READ_WRITE | mf.COPY_HOST_PTR, hostbuf=a)

    # 5. Define and build the OpenCL kernel program
    prg = cl.Program(ctx, """
    __kernel void twice(__global float *a) {
        int gid = get_global_id(0);
        a[gid] = 2*a[gid];
    }
    """).build()

    # 6. Execute the kernel
    # global_size is the total number of work-items
    # local_size (None) lets the OpenCL driver decide
    prg.twice(queue, a.shape, None, a_buf)

    # 7. Create output array and transfer data back to host
    result = np.empty_like(a)
    cl.enqueue_copy(queue, result, a_buf).wait()

    # 8. Verify the result
    print("Original first 5 elements:", a[:5])
    print("Resulting first 5 elements:", result[:5])
    assert np.allclose(result, 2*a)
    print("Kernel executed successfully and results verified!")

if __name__ == '__main__':
    run_opencl_kernel()