possible problems & solutions

darktable will detect OpenCL run-time errors automatically. On detecting an error, it will then reprocess everything on the CPU. While this will slow down processing it should not affect the end result.

There can be various reasons why OpenCL might fail during the initialization phase. OpenCL depends on hardware requirements and on the presence of certain drivers and libraries. In addition all these have to fit in terms of maker, model and revision number. If anything does not fit (e.g. your graphics driver – loaded as a kernel module – does not match the version of your libOpenCL.so) OpenCL support will likely not be available.

In this case, the best thing to do is start darktable from a console with darktable -d opencl.

This will give additional debugging output about the initialization and use of OpenCL. First, if you find a line that starts with [opencl_init] FINALLY ... that should tell you whether OpenCL support is available for you or not. If initialization failed, look at the messages above for anything that reads like could not be detected or could not be created. Check if there is a hint about where it failed.

Here are a few cases that have been observed in the past:

  • darktable states that no OpenCL aware graphics card is detected or that the available memory on your GPU is too low and the device is discarded. In that case you might need to buy a new card if you really want OpenCL support.

  • darktable finds your libOpenCL.so but then tell you that it couldn’t get a platform. NVIDIA drivers will often give error code -1001 in this case. This happens because libOpenCL.so is only a wrapper library. For the real work further vendor-specific libraries need to be loaded. This has failed for some reason. There is a structure of files in /etc/OpenCL on your system that libOpenCL.so consults to find these libraries. See if you can find something fishy in there and try to fix it. Often the required libraries cannot be found by your system’s dynamic loader. Giving full path names might help.

  • darktable states that a context could not be created. This often indicates a version mismatch between the loaded graphics driver and libOpenCL. Check if you have left-over kernel modules or graphics libraries from an older installation and take appropriate action. When in doubt, perform a clean reinstall of your graphics driver. Sometimes, immediately after a driver update, the loaded kernel driver does not match the newly installed libraries. In this case reboot your system before trying again.

  • darktable crashes during startup. This can happen if your OpenCL setup is completely broken or if your driver/library contains a severe bug. If you can’t fix it, you can still use darktable with option --disable-opencl, which will skip the entire OpenCL initialization step.

  • darktable fails to compile its OpenCL source files at run-time. In this case you will see a number of error messages looking like typical compiler errors. This could indicate an incompatibility between your OpenCL implementation and darktable’s interpretation of the standard. In that case please raise an issue on github and we will try to assist. Please also report if you see significant differences between CPU and GPU processing of an image.

  • you have installed a number of OpenCL drivers meant for the same hardware, this will always lead to severe problems and must strictly be avoided. On Windows systems you often have the Microsoft OpenCLon12 driver installed via the OpenCL Compatibility Pack. Inspect and check at preferences > processing > OpenCL.

  • A few emulated-on-CPU implementations of OpenCL also exist, coming as drivers provided by INTEL or AMD. We have observed that they do not provide any speed gain versus the compiler-optimized CPU code. Therefore darktable simply discards these drivers / devices by default.