program invocation on darktable 5.6 user manual

invocation per OS

Mon, 01 Jan 0001 00:00:00 +0000

darktable and the other binaries (e.g. darktable-cltest) can be executed from the console as follows:

Linux

Installed as package or snap: darktable
Flatpak: flatpak run org.darktable.Darktable
- To run e.g. darktable-cltest: flatpak run --command=darktable-cltest org.darktable.Darktable --arguments-go-here.
AppImage: Navigate to containing folder, then ./darktable.Appimage (or however you named the file)
- To run e.g. darktable-cltest: ./darktable.Appimage darktable-cltest
- An additional option to run the various binaries included in darktable (e.g. darktable-cltest or darktable-cli) is through a symbolic link:
  - Create a symbolic link to your AppImage and call it e.g. darktable-cli.
  - Then, when calling the AppImage through the symbolic link with ./darktable-cli, the code inside the package checks if there is a binary file inside the AppImage with a name that matches the symlink name. If so, it will be run instead of the default one.

Windows

darktable

Mon, 01 Jan 0001 00:00:00 +0000

The darktable binary starts darktable with its GUI and full functionality. This is the standard way to use darktable. The command to run the binary depends on your OS.

The following command line parameters are available:

darktable [-d {all,act_on,ai,cache,camctl,camsupport,common,control,
               dev,expose,fswatch,imageio,input,ioporder,lighttable,lua,
               masks,memory,nan,opencl,params,perf,pipe,print,pwstorage,
               signal,sql,tiling,undo,verbose}]
          [--d-signal <signal>]
          [--d-signal-act <all,raise,connect,disconnect,print-trace>]
          [--disable-pipecache]
          [<input file>|<image folder>]
          [--version]
          [--disable-opencl]
          [--configdir <user config directory>]
          [--library <library file>]
          [--datadir <data directory>]
          [--moduledir <module directory>]
          [--tmpdir <tmp directory>]
          [--cachedir <user cache directory>]
          [--localedir <locale directory>]
          [--luacmd <lua command>]
          [--noiseprofiles <noiseprofiles json file>]
          [--conf <key>=<value>]
          [-t <num openmp threads>]

All parameters are optional. In most cases darktable should be started without any additional parameters, in which case darktable uses suitable defaults.

darktable-cli

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cli binary starts the command line interface variant of darktable which allows images to be exported.

This variant does not open any display – it works in pure console mode without launching a GUI. This mode is particularly useful for servers running background jobs.

darktable-cli can be called with the following command line parameters:

darktable-cli [<input file or folder>]
              [<xmp file>]
              <output file or folder>
              [--width <max width>]
              [--height <max height>]
              [--hq <0|1|true|false>]
              [--upscale <0|1|true|false>]
              [--style <style name>]
              [--style-overwrite]
              [--apply-custom-presets <0|1|false|true>]
              [--out-ext <extension>]
              [--import <file or dir>]
              [--library <path>]
              [--icc-type <type>]
              [--icc-file <file>]
              [--icc-intent <intent>]
              [--verbose]
              [--help [option]]
              [--core <darktable options>]

The user must supply an input filename and an output filename. All other parameters are optional.

darktable-generate-cache

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-generate-cache binary updates darktable’s thumbnail cache. Invoke this program to generate all missing thumbnails in the background when your computer is idle.

darktable-generate-cache can be called with the following command line parameters:

darktable-generate-cache
              [-h, --help]
              [--version]
              [--min-mip <0-8>] [-m, --max-mip <0-8>]
              [--min-imgid <N>] [--max-imgid <N>]
              [--core <darktable options>]

All parameters are optional. If started without parameters darktable-generate-cache uses reasonable defaults.

-h, --help: Display usage information and terminate.
--version: Display copyright and version information and terminate.
--min-mip <0-8>, -m, --max-mip <0-8>: darktable can store thumbnails with up to eight different resolution steps for each image. These parameters define the maximum resolution to be generated (defaults to a range of 0-2). There is normally no need to generate all possible resolutions here – missing ones will be automatically generated by darktable the moment they are needed. When asked to generate multiple resolutions at once, the lower-resolution images are quickly downsampled from the highest-resolution image.
--min-imgid <N>, --max-imgid <N>: Specifies the range of internal image IDs from the database to work on. If no range is given, darktable-generate-cache will process all images.
--core <darktable options>: All command line parameters following --core are passed to the darktable core and handled as standard parameters. See the darktable binary section for a detailed description.

darktable-chart

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-chart binary is a dedicated utility to create styles out of pairs of images such as RAW+JPEG with in-camera processing. Details about its usage can be found in the using darktable-chart section.

darktable-chart can either start a GUI or be used as a command-line program.

darktable-chart
              [--help]
              [<input Lab pfm file>]
              [<cht file>]
              [<reference cgats/it8 or Lab pfm file>]

All parameters are optional, however, if you want to supply the second file name you also need to supply the first one. Starting darktable-chart this way opens a special GUI (details can be found in the using darktable-chart section).

darktable-cltest

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cltest binary checks if there is a usable OpenCL environment on your system that darktable can use. It emits some debug output that is equivalent to calling darktable -d opencl and then terminates.

darktable-cltest is called without command line parameters.

darktable-cmstest

Mon, 01 Jan 0001 00:00:00 +0000

The darktable-cmstest binary (Linux only) investigates whether the color management subsystem of your computer is correctly configured and displays some useful information about the installed monitor profile(s).

darktable-cmstest is called without command line parameters.

purge_non_existing_images.sh

Mon, 01 Jan 0001 00:00:00 +0000

Find and remove entries from the library database referencing images that no longer exist in the filesystem. You must close darktable before running this script.

The script can be called with the following command line parameters:

purge_non_existing_images.sh [-c|--configdir <path>]
                             [-l|--library <path>]
                             [-p|--purge]

Run the script with no options to perform a “dry run”, which generates a report of the missing files without committing any changes to the database.

The available options are:

gimp integration

Mon, 01 Jan 0001 00:00:00 +0000

GIMP can use darktable to open a Raw file if the darktable executable is on the PATH. If the GIMP user opens a RAW file, then GIMP invokes darktable with some special command line parameters to get a temporary file for GIMP to work with, as follows:

darktable --gimp [version]
                 [file <path>]
                 [thumb <path> <dim>]

In all cases, darktable will report its result to GIMP wrapped in tags like this (where <res> depends on the command given):