Registry / ai-ml / pyopencl

pyopencl

JSON →
library2026.1.2pypypi✓ verified 87d ago

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 pyopencl
INSTALL
IMPORT
SIG · PYOPENCL
P
pyopencl
ai-mlpythonv2026.1.2
Install
4.1s avg
Import
524ms
Disk
94MB
Pass rate
6/ 10
Env Coverage6 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2026.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 4.13s
py 3.11
✕ build_error
✓ 3.98s
py 3.12
✕ build_error
✓ 3.78s
py 3.13
✕ build_error
✓ 3.83s
py 3.9
✓ —
✓ 4.73s
94MB installed
● package 94MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cl
import pyopencl as cl
array
import pyopencl.array as cla
Common alias for convenience when working with GPU arrays.

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()
Debug
Known issues
breakingThe `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`).
affects: >=2025.2.5
gotchaPyOpenCL 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.
affects: All
gotchaMixing 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.
affects: All
gotchaDirect 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.
affects: All
deprecatedMany 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.
affects: Before 2011.1 (deprecated `context` argument of `pyopencl.array.to_device`), generally before 2013.1 (introduction of `cl.enqueue_copy`).
Errors
Common errors & fixes
ImportError: DLL load failed: The specified procedure could not be found.
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
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
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
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.
Upgrade
Version history
2026.1.2latest on PyPI · released Jan 16, 2026
Audit
Dependencies
numpyrequiredEssential for array operations, data transfer, and numerical computations within PyOpenCL programs.
pytoolsrequiredA utility library that PyOpenCL depends on for various internal functionalities.
makorequiredUsed by PyOpenCL for templating and kernel source code generation.
OpenCL ICD/DriversrequiredRequired runtime component; provides access to the underlying OpenCL hardware (GPU, CPU, etc.). This is an external system dependency, not a Python package.
Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
1
Resources
pyopencl — pip install pyopencl · libregistry