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. Check if you 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 visit the developers in IRC in #darktable on FreeNode or on the developers mailing list at darktable-dev@lists.darktable.org and report the problem. Chances are good that we can help you. Please also report if you see significant differences between CPU and GPU processing of an image.

A few 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 our hand-optimized CPU code. Therefore darktable simply discards these devices by default. This behavior can be changed by setting the configuration variable opencl_use_cpu_devices (in $HOME/.config/darktablerc) to TRUE.