{"id":8507,"library":"pyopencl","title":"PyOpenCL","description":"PyOpenCL is a Python wrapper for OpenCL, providing access to GPUs, CPUs, and other parallel compute devices for high-performance computing. It offers a Pythonic, object-oriented interface, integrates seamlessly with NumPy, and includes automatic error checking. The library is actively maintained with frequent releases, and its current version is 2026.1.2.","status":"active","version":"2026.1.2","language":"en","source_language":"en","source_url":"https://github.com/inducer/pyopencl","tags":["OpenCL","GPU computing","parallel programming","HPC","scientific computing","numerical computing"],"install":[{"cmd":"pip install pyopencl","lang":"bash","label":"Install PyOpenCL"}],"dependencies":[{"reason":"Essential for array operations, data transfer, and numerical computations within PyOpenCL programs.","package":"numpy"},{"reason":"A utility library that PyOpenCL depends on for various internal functionalities.","package":"pytools"},{"reason":"Used by PyOpenCL for templating and kernel source code generation.","package":"mako"},{"reason":"Required runtime component; provides access to the underlying OpenCL hardware (GPU, CPU, etc.). This is an external system dependency, not a Python package.","package":"OpenCL ICD/Drivers","optional":false}],"imports":[{"symbol":"cl","correct":"import pyopencl as cl"},{"note":"Common alias for convenience when working with GPU arrays.","symbol":"array","correct":"import pyopencl.array as cla"}],"quickstart":{"code":"import pyopencl as cl\nimport numpy as np\n\ndef run_opencl_kernel():\n    # 1. Create a context\n    try:\n        ctx = cl.create_some_context()\n    except cl.LogicError as e:\n        print(f\"Error creating OpenCL context: {e}\")\n        print(\"Please ensure you have OpenCL drivers/ICD installed.\")\n        return\n\n    # 2. Create a command queue\n    queue = cl.CommandQueue(ctx)\n\n    # 3. Prepare host data\n    a = np.random.rand(50000).astype(np.float32)\n\n    # 4. Create device buffers and transfer data\n    mf = cl.mem_flags\n    a_buf = cl.Buffer(ctx, mf.READ_WRITE | mf.COPY_HOST_PTR, hostbuf=a)\n\n    # 5. Define and build the OpenCL kernel program\n    prg = cl.Program(ctx, \"\"\"\n    __kernel void twice(__global float *a) {\n        int gid = get_global_id(0);\n        a[gid] = 2*a[gid];\n    }\n    \"\"\").build()\n\n    # 6. Execute the kernel\n    # global_size is the total number of work-items\n    # local_size (None) lets the OpenCL driver decide\n    prg.twice(queue, a.shape, None, a_buf)\n\n    # 7. Create output array and transfer data back to host\n    result = np.empty_like(a)\n    cl.enqueue_copy(queue, result, a_buf).wait()\n\n    # 8. Verify the result\n    print(\"Original first 5 elements:\", a[:5])\n    print(\"Resulting first 5 elements:\", result[:5])\n    assert np.allclose(result, 2*a)\n    print(\"Kernel executed successfully and results verified!\")\n\nif __name__ == '__main__':\n    run_opencl_kernel()","lang":"python","description":"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."},"warnings":[{"fix":"Update code to use lower-case attribute names for `Event.profile` access (e.g., `event.profile.end`).","message":"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`).","severity":"breaking","affected_versions":">=2025.2.5"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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. ","severity":"gotcha","affected_versions":"All"},{"fix":"For thread-safe kernel execution, create a separate kernel object for each thread that will enqueue calls, or use appropriate locking mechanisms.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `cl.enqueue_copy(queue, dest, src)` for all data transfers between host and device or between device buffers.","message":"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.","severity":"deprecated","affected_versions":"Before 2011.1 (deprecated `context` argument of `pyopencl.array.to_device`), generally before 2013.1 (introduction of `cl.enqueue_copy`)."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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).","error":"ImportError: DLL load failed: The specified procedure could not be found."},{"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.","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).","error":"pyopencl.LogicError: clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR"},{"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.","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.","error":"pyopencl.RuntimeError: clBuildProgram failed: invalid build options"},{"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.","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.","error":"pyopencl.LogicError: clEnqueueNDRangeKernel failed: invalid work item size"}]}