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.
pip install pyopenclVerified import paths — ran on the pinned version, not inferred.
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.
Update code to use lower-case attribute names for `Event.profile` access (e.g., `event.profile.end`).
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.
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.
For thread-safe kernel execution, create a separate kernel object for each thread that will enqueue calls, or use appropriate locking mechanisms.
Use `cl.enqueue_copy(queue, dest, src)` for all data transfers between host and device or between device buffers.
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.
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.
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.
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.