Install your OpenCL GPU drivers if you have a GPU.
On Windows 11, it seems that the system OpenCL drivers for Intel embedded GPU cause issues (black images), especially with newer generation CPU. You may want to remove Windows drivers and install Intel ones .
The Ansel project provides an official .exe package, built for the stable, pre-release and experimental channels. This is the recommended way of installing Ansel, since it is fresh from the repository, always up-to-date and ships updated lens databases for Lensfun.
MSYS will initialize a personal Unix-like /home folder, by default located in C:\\msys64\home\USERNAME where USERNAME is your current Windows username. If your username contains non-latin characters, like accentuated letters, the clashes between Windows encoding and Linux encoding will make the compilation fail on directory pathes issues. In that case, create a new directory in C:\\msys64\home\USERNAME_WITHOUT_ACCENTS, and in the MSYS terminal, do cd /home/USERNAME_WITHOUT_ACCENT.
Step 6: Using a text editor, eg. MS Notepad - Modify the .bash_profile file in your $HOME directory and add the following lines:
1# Added as per http://wiki.gimp.org/wiki/Hacking:Building/Windows2export PREFIX="/ucrt64"3export LD_LIBRARY_PATH="$PREFIX/lib:$LD_LIBRARY_PATH"4export PATH="$PREFIX/bin:$PATH"
Step 7: By default CMake will only use one core during the build process. To speed things up, using a text editor, eg. MS Notepad, you might wish to add a line like:
After this, you will need to double-click and install the ansel.exe found in the build/bin folder. This package will be portable and be installable on other platforms.
Building with AddressSanitizer (ASan)
AddressSanitizer is a compiler instrumentation that catches memory bugs (use-after-free, heap buffer overflows, double-free, etc.) at the exact moment they happen, with the offending line of code and both the allocation and the faulty-access call stacks. This is invaluable for chasing a crash that otherwise only shows up much later, or not at all, in a normal build — typically, a heap corruption that Windows only notices (and reports as an opaque address) the next time it happens to touch the damaged memory, long after the actual bug.
This is a debug build, meant for hunting a specific bug, not for daily use: keep it in its own prefix, separate from your normal install.
1. Install a suitable Clang toolchain
MSYS2’s own UCRT64 Clang does not ship an ASan runtime for the x86_64-w64-mingw32 target (only builtins/fuzzer/profile are provided, no asan_*). llvm-mingw is a separate, prebuilt Clang distribution that does include it.
Extract it under /opt, e.g. so that /opt/llvm-mingw-<date>-ucrt-x86_64/bin/clang++.exe exists.
Note
This is a separate toolchain from the one used for a normal build: it is only ever referenced explicitly, below, through CC/CXX, so it cannot affect a normal build.
2. Create the compiler wrappers
llvm-mingw’s Clang bundles its own libc++, which is what its ASan runtime is built to work with — but it does not know about MSYS2’s own layout, and mixing it with MSYS2’s headers/libraries (unavoidable, since Ansel links against MSYS2-built GTK, glib, etc.) causes two separate problems: a <math.h>/isnan/signbit macro clash against libc++’s own headers, and llvm-mingw’s Clang defaulting to a C++ standard library (libc++) that is not the one the rest of the build actually links against (MSYS2’s own libstdc++). Two small wrapper scripts route it to MSYS2’s libstdc++ instead, and add the search paths llvm-mingw has no reason to know about on its own.
Adjust the GCC version in the paths below (15.2.0) to whatever ls /ucrt64/include/c++/ reports on your system.
1@echo off
2REM C compiler wrapper: makes bare -lname libraries that live under MSYS2 ucrt64's lib3REM dir (e.g. -lexchndl, DrMingw's crash handler) resolvable, since llvm-mingw's own4REM clang.exe has no reason to know that directory exists otherwise.5"%~dp0clang.exe" -L C:/msys64/ucrt64/lib -Wno-unused-command-line-argument %*
Use -DCMAKE_BUILD_TYPE=Debug, not Release/RelWithDebInfo. The latter enable LTO (-flto=thin), which produces bitcode-only .obj files this cross-compiler setup cannot reliably link. Debug is also the generally-recommended build type for sanitizers regardless: no optimizer reordering to fight with when reading a stack trace.
4. Copy the ASan runtime DLLs
ansel.exe ends up dynamically linked against six DLLs that are not on PATH by default. Copy them next to the installed binaries:
The first three are llvm-mingw’s own ASan/libc++/unwind runtimes (the ASan runtime itself depends on libc++.dll even though Ansel’s own code is built against libstdc++, and Clang defaults to llvm-mingw’s own libunwind for exception handling); the last three are libstdc++’s own dependencies.
Reproduce whatever you are chasing, then close Ansel normally. If ASan catches anything, its report is printed directly to the terminal — redirect it to a file (> ansel_asan.log 2>&1) if you want to keep a copy.
Note
GTK and glib are precompiled MSYS2 DLLs, not built with ASan. A pointer crossing that boundary (allocated on one side, freed on the other) trips a bad-free that has nothing to do with whatever you are actually chasing — this fires right at startup, from glib’s own type system init, before any Ansel code runs. halt_on_error=0 logs it and keeps going instead of aborting there; alloc_dealloc_mismatch=0 and allocator_may_return_null=1 suppress the same class of cross-allocator false positive elsewhere. This is a limitation of instrumenting one executable in a process otherwise made of non-instrumented DLLs, not a bug in Ansel.
VS Code setup
To make debugging easier with VS Code, you can use the UCRT64 terminal within the program, which is better suited than the standard Windows terminal. For example, you can use GDB and simply Ctrl + click on relevant lines in the debugger output to jump directly to the corresponding line in the code editor.
In some situations, you will need to start Ansel in command line, with arguments modifying its default behaviour, to test or debug issues:
If you built yourself, start the MSYS2 MINGW64 terminal (from the applications menu), and execute /opt/ansel/bin/ansel.exe,
If you installed from the EXE package, open the Windows terminal (cmd.exe) and execute "C:\Programs Files\ansel\bin\ansel" (assuming you installed Ansel in the default directory, suggested by the installer).
For example, if you note issues with OpenCL, you could start Ansel with OpenCL entirely disabled using "C:\Programs Files\ansel\bin\ansel" --disable-opencl.
The caveat though is the debugging commands (-d OPTION) don’t output messages to the terminal, as they do on Unix, because of issues with Windows. Instead, the output will be written in an ansel-log.txt text file, in your cache directory. Start the help of the software ( runing "C:\Programs Files\ansel\bin\ansel" -h), and the last line should tell you where the file will be located after the line note: debug log and output will be written to this file: PATH. Typically, it should be C:\Users\USERNAME\AppData\Local\Microsoft\Windows\INetCache\ansel on Windows 10.
OpenCL
Darktable blacklists all Intel OpenCL drivers to prevent issues, because of an history of bad drivers. In practice, since Intel Neo, things are better and reasonably-old Intel platforms are well supported, so the blacklist is removed on Ansel. OpenCL issues (typically: black images) are still regularly reported with brand-new hardware.
If you find yourself in this situation, you have several mitigation options:
Try to install a newer or an older version of your GPU driver.
If you have a discrete GPU (Nvidia or AMD), you can disable the Intel embedded GPU:
By entirely removing the Intel OpenCL driver (use your software manager to locate it), so Ansel uses only your discrete driver,
By disabling the Intel GPU from within Ansel: open Preferences → Processing → CPU / GPU / memory, find that GPU’s section, and switch off its “Enable” checkbox. This only affects that device — your discrete GPU (or the CPU path) keeps working normally, and no file needs editing.
Try to change the build options for OpenCL kernels — this one has no equivalent in Preferences yet, so it still needs the config file:
Locate the anselrc text file on your system (typically in C:\Users\USERNAME\AppData\Local\ansel),
Open it and locate the line starting with cldevice_v4/N/YOUR_DEVICE/building=, where N is a small index and YOUR_DEVICE is the name of your GPU as reported by its driver. The default value is -cl-mad-enable -cl-no-signed-zeros; yours may differ if you already changed it,
Clear the building options, so you get cldevice_v4/N/YOUR_DEVICE/building= (nothing after =)
If you don’t have a discrete GPU and the Intel one is your only one:
Start the application with OpenCL disabled at all with COMMAND --disable-opencl (see the previous section for the actual system command to run, depending on your installation)
Disable the Intel GPU from Preferences (see point 1.2. above)
Memory allocation
Ansel uses virtual memory pre-allocation for fast memory access. Virtual memory needs to be enabled on your system and the pagefile size required by Ansel should be available on your system. If, at startup, you see errors like :
it means the system refused to allocate the requested memory. This can happen on gamers PC where performance optimizations have been made.
Diagnose
Open Task Manager → Performance → Memory and check Committed: X / Limit. X is the currently-used virtual memory. If it is close to Limit you will have to close applications using it.
Fix
The first approach is to enable or increase the virtual memory on your system. Go to System Properties → Advanced → Performance → Virtual Memory and set pagefile to system managed or several GB.
If this is not enough, the second approach is to reduce Ansel memory consumption. memory_os_headroom can be adjusted directly from Preferences → Processing → CPU / GPU / memory, without editing any file. host_memory_limit has no equivalent in Preferences yet, so it still needs the config file: open C:\%LOCALAPPDATA%\ansel\anselrc with a text editor and locate the lines :
When set to -1 or 0, host_memory_limit detects all the RAM available on your system and will allocate to Ansel host_memory_limit - memory_os_headroom. Values are in MiB. To manually control this, you can set host_memory_limit=4000 (4 GiB) as a starting point, then try allocating more if that works.
Note
memory_os_headroom is clamped between 1024 (1 GiB) and a third of the RAM Ansel detects: setting it to 0 will not actually leave zero headroom, it will floor to 1024. If you need to go below that, lowering host_memory_limit itself is the only way.