Install on Windows

Prerequisites

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 .

See the caveats section below for more details.

EXE package (recommended)

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.

Downloads

• Get the latest EXE package 
• Find earlier EXE packages .

Building from source code manually

• Step 1: Install MSYS2 (instructions and prerequisites can be found on the official website: https://www.msys2.org )
• Step 2: Using the MSYS terminal - Update the base system until no further updates are available by repeating:

  1$ pacman -Syu

• Step 3: Using the UCRT64 terminal - Clone the Ansel git repository (in this example into ~/ansel):

  1$ cd ~
  2$ git clone --depth 1 https://github.com/aurelienpierreeng/ansel.git
  3$ cd ansel
  4$ git submodule init
  5$ git submodule update

• Step 4: Using the UCRT64 terminal - Install all build dependencies using the script from the repository:

  1$ ./packaging/install-deps-windows-msys2.sh

• Step 5: Using the UCRT64 terminal - Update your lensfun database:

  1$ lensfun-update-data

• 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/Windows
  2export 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:

  1export CMAKE_BUILD_PARALLEL_LEVEL="8"

  to your ~/.bash_profile file. This would use 8 cores.

• Step 8: Using the UCRT64 terminal - Execute the following command to activate profile changes:

  1$ . .bash_profile

• Step 9: Using the UCRT64 terminal - Build and install Ansel:

  • Variant 1: with all contextual optimizations enabled for your hardware:

    1$ mkdir build
    2$ cd build
    3$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DBINARY_PACKAGE_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/opt/ansel ../.
    4$ cmake --build .
    5$ cmake --install .

    After this, Ansel will be installed in /opt/ansel directory and can be started by typing /opt/ansel/bin/ansel.exe in MSYS2 UCRT64 terminal.
  • Variant 2: with only generic optimizations and producing an installable EXE package:

    1$ mkdir build
    2$ cd build
    3$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DBINARY_PACKAGE_BUILD=ON -DCMAKE_INSTALL_PREFIX=/opt/ansel ../.
    4$ cmake --build . --target package
    5$ cmake --install .

    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.

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.

• To add UCRT64 terminal:

  • Open settings.json

  • Insert this code in the line before the last } :

    Warning

    The preceding item must end with a ,

    1"terminal.integrated.profiles.windows": {
    2  "UCRT64": {
    3    "path": "C:\\MSYS2\\usr\\bin\\bash.exe",
    4    "env": {
    5        "MSYSTEM": "UCRT64",
    6        "CHERE_INVOKING": "1"},
    7    "args": [ "--login", "-i"],
    8  }
    9}

• To make it the default terminal in VS Code:

  • Insert this code in the line before the last } :

  Warning

  The preceding item must end with a ,

  1"terminal.integrated.defaultProfile.windows": "UCRT64"

Caveats

Starting in command line (with arguments)

In some situations, you will need to start Ansel in command line, with arguments modifying its default behaviour, to test or debug issues:

1. If you built yourself, start the MSYS2 MINGW64 terminal (from the applications menu), and execute /opt/ansel/bin/ansel.exe,
2. 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:

0. Try to install a newer or an older version of your GPU driver.
1. If you have a discrete GPU (Nvidia or AMD), you can disable the Intel embedded GPU:
   1. By entirely removing the Intel OpenCL driver (use your software manager to locate it), so Ansel uses only your discrete driver,
   2. By entirely disabling the Intel GPU in Ansel config:
      • Locate the anselrc text file on your system (typically in C:\Users\USERNAME\AppData\Local\ansel),
      • Open it and locate the line cldevice_v4_YOUR_DEVICE=0 250 0 16 16 128 0 0 0.053989 where YOUR_DEVICE is the name of your GPU (possibly associated with a driver version),
      • On that line, change the 8th (penultimate) digit from 0 to 1, so you get cldevice_v4_YOUR_DEVICE=0 250 0 16 16 128 0 1 0.053989,
2. Try to change the build options for OpenCL kernels:
   • Locate the anselrc text file on your system (typically in C:\Users\USERNAME\AppData\Local\ansel),
   • Open it and locate the line cldevice_v4_YOUR_DEVICE_building=-cl-fast-relaxed-math where YOUR_DEVICE is the name of your GPU (possibly associated with a driver version), and the options after = may be different from this example,
   • Clear the building options, so you get cldevice_v4_YOUR_DEVICE_building= (nothing after =)
3. If you don’t have a discrete GPU and the Intel one is your only one:
   1. 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)
   2. Disable the Intel GPU in Ansel config (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 :

1couldn't alloc map (VirtualAlloc error 1455)
2ERROR: can't init pixelpipe cache, aborting.

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. Open C:\%LOCALAPPDATA%\ansel\anselrc with a text editor and locate the lines :

1host_memory_limit=-1
2...
3memory_os_headroom=25000

When set to -1, 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) and memory_os_headroom=0 as a starting point. If that works, you can try allocating more.