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

• Install MSYS2 (instructions and prerequisites can be found on the official website: https://www.msys2.org)

• Start the MSYS terminal and update the base system until no further updates are available by repeating:

  $ pacman -Syu
  

• From the MSYS terminal, install x64 developer tools, x86_64 toolchain and git:

  $ pacman -S --needed base-devel intltool git
  $ pacman -S --needed mingw-w64-x86_64-{toolchain,cmake,ninja,nsis,autotools}
  

• Install required libraries and dependencies for darktable:

  $ pacman -S --needed mingw-w64-x86_64-{exiv2,lcms2,lensfun,dbus-glib,openexr,sqlite3,libxslt,libsoup,libavif,libheif,libwebp,libsecret,lua,graphicsmagick,openjpeg2,gtk3,pugixml,libexif,osm-gps-map,drmingw,gettext,python3,iso-codes,python3-jsonschema,python3-setuptools}
  

• Install optional libraries and dependencies:

  • for cLUT

    $ pacman -S --needed mingw-w64-x86_64-gmic
    

  • for NG input with midi devices

    $ pacman -S --needed mingw-w64-x86_64-portmidi
    

• Open the MINGW64 terminal (from the application menu) and update your lensfun database:

  $ lensfun-update-data
  

• Modify the .bash_profile file in your $HOME directory and add the following lines:

  # Added as per http://wiki.gimp.org/wiki/Hacking:Building/Windows
  export PREFIX="/mingw64"
  export LD_LIBRARY_PATH="$PREFIX/lib:$LD_LIBRARY_PATH"
  export PATH="$PREFIX/bin:$PATH"
  

• By default CMake will only use one core during the build process. To speed things up you might wish to add a line like:

  export CMAKE_BUILD_PARALLEL_LEVEL="8"
  

  to your ~/.bash_profile file. This would use 8 cores.
• Execute the following command to activate profile changes:

  $ . .bash_profile
  

• From the MINGW64 terminal, clone the darktable git repository (in this example into ~/ansel):

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

• Finally build and install Ansel:
  • Variant 1: with all contextual optimizations enabled for your hardware:

    $ mkdir build
    $ cd build
    $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DBINARY_PACKAGE_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/opt/ansel ../.
    $ cmake --build .
    $ 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 MINGW64 terminal.
  • Variant 2: with only generic optimizations and producing an installable EXE package:

    $ mkdir build
    $ cd build
    $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DBINARY_PACKAGE_BUILD=ON -DCMAKE_INSTALL_PREFIX=/opt/ansel ../.
    $ cmake --build . --target package
    $ 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.

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)