Chapter 1. Overview

darktable is an open source photography workflow application and raw developer, a virtual lighttable and darkroom for photographers.

It manages your digital negatives in a database, lets you view them through a zoomable lighttable and enables you to develop raw images and enhance them.

General Features

  • darktable runs on GNU/Linux / GTK3, Mac OS X / macports and Solaris 11 / GTK3.

  • Fully non-destructive editing.

  • All darktable core functions operate on 4x32-bit floating point pixel buffers for high accuracy processing, preventing banding and color breaks.

  • darktable makes heavy use of Streaming SIMD Extensions 2 (SSE2) instructions of the CPU to speed up processing. In fact, darktable requires either an SSE2-capable x86 processor or an ARM64 processor.

  • GPU acceleration via OpenCL (runtime detection and enabling).

  • Most image processing is done in CIELab color space, which is much larger than the gamut of modern displays, printers or even human vision.

  • Full color managed display with softproofing and gamut-check. Built-in ICC profile support for export: sRGB, Adobe RGB, XYZ and linear RGB.

  • A collect module allows you to execute flexible database queries, search your images by tags, image rating (stars), color labels and many more. Filtering and sorting your collections within the base query or simple tagging by related tags are useful tools in your every-day photo workflow.

  • Import a variety of standard, raw and high dynamic range image formats (e.g. JPEG, CR2, DNG, OpenEXR, PFM, ...).

  • darktable has a zero-latency fullscreen, zoomable user interface through multi-level software caches.

  • Tethered shooting.

  • The powerful export system supports Picasa webalbum, flickr upload, disk storage, 1:1 copy, email attachments and can generate a simple html-based web gallery. darktable allows you to export to low dynamic range (JPEG, JPEG2000, PNG, TIFF, PDF), 16-bit (PPM, TIFF), or linear high dynamic range (PFM, EXR) images.

  • darktable uses both XMP sidecar files as well as its fast database for saving metadata and processing settings. All Exif data is read and written using libexiv2.

  • darktable comes with more than 60 image operation modules which cover everything from basic operations, tonal value changes, color manipulation, correction of common image defects to artistic effects.

  • Many darktable modules can be combined with blending operators for even more development options.

  • A powerful mask feature gives you fine control on module's effect to different parts of an image. You can at your choice draw a mask using various shapes or define a parametric mask based on pixel values.

  • Most modules can exist as multiple instances. Together with the mask feature, you can let an operation have different effects on different parts of the image.

  • darktable introduces a highly efficient, yet simple single-click denoiser that always just works™. It's designed as a module where the denoising performance only depends on camera and ISO setting. A database of profiles contains parameters for well above 200 popular camera models.

  • darktable comes with a versatile scripting interface for functionality enhancement using Lua as a scripting language.

  • Images containing geo coordinates can be displayed on a map with various map sources at your choice. Geo coordinates can be assigned to images by manually placing them on the map, or by automatically applying GPX track data.

  • darktable has a built-in slideshow feature that lets you display your collection of images fullscreen.

  • A versatile print module lets you send your image to a connected printer with full color management support.

1.1. Program invocation

darktable comes with two main binaries: the standard GUI variant which is started by calling darktable and a command line interface variant which is started by calling darktable-cli . Additionally darktable is shipped with some further binaries for special purposes.

1.1.1. darktable binary

This binary starts darktable with its GUI and full functionality; it is the standard way of using darktable.

darktable is called with the following command line parameters:

darktable [-d {all,cache,camctl,camsupport,control,dev,
               fswatch,input,lighttable,masks,memory,nan,
               opencl,perf,pwstorage,print,sql}]
          [<input file>|<image folder>]
          [--version]
          [--disable-opencl]
          [--library <library file>]
          [--datadir <data directory>]
          [--moduledir <module directory>]
          [--tmpdir <tmp directory>]
          [--configdir <user config directory>]
          [--cachedir <user cache directory>]
          [--localedir <locale directory>]
          [--luacmd <lua command>]
          [--noiseprofiles <noiseprofiles json file>]
          [--conf <key>=<value>]

All parameters are optional; in most cases users will start darktable without any additional parameters in which case darktable uses suitable defaults.

-d

This option enables debug output to the terminal. There are several subsystems of darktable and debugging of each of them can be activated separately. You can use this option multiple times if you want debugging output of more than one subsystem.

<input file>|<image folder>

You may optionally supply the filename of an image or the name of a folder containing image files. If a filename is given darktable starts in darkroom view with that file opened. If a folder is given darktable starts in lighttable view with the content of that folder as the current collection.

--version

This option causes darktable to print its version number, a copyright notice, some other useful information, and then terminate.

--disable-opencl

This option prevents darktable from initializing the OpenCL subsystem. Use this option in case darktable crashes at startup due to a defective OpenCL implementation.

--library <library file>

darktable keeps image information in an sqlite database for fast access. The default location of that database file is $HOME/.config/darktable/library.db. You may give an alternative location, e.g. if you want to do some experiments without compromising your original library.db. If the database file does not exist, darktable creates it for you. You may also give :memory: as a library file in which case the database is kept in system memory – all changes are discarded when darktable terminates.

Whenever darktable starts, it will lock the library to the current user. It does this by writing the current process identifier (PID) into a lock file <library file>.lock next to the library specified. If darktable finds an existing lock file for the library, it will terminate immediately.

--datadir <data directory>

This option defines the directory where darktable finds its runtime data. The default place depends on your installation. Typical places are /opt/darktable/share/darktable/ and /usr/share/darktable/.

--moduledir <module directory>

darktable has a modular structure and organizes its modules as shared libraries for loading at runtime. With this option you tell darktable where to look for its shared libraries. The default place depends on your installation; typical places are /opt/darktable/lib64/darktable/ and /usr/lib64/darktable/.

--tmpdir <tmp directory>

The place where darktable stores its temporary files. If this option is not supplied darktable uses the system default.

--configdir <config directory>

This option defines the directory where darktable stores the user specific configuration. The default place is $HOME/.config/darktable/.

--cachedir <cache directory>

darktable keeps a cache of image thumbnails for fast image preview and of precompiled OpenCL binaries for fast startup. By default the cache is located in $HOME/.cache/darktable/. There may exist multiple thumbnail caches in parallel – one for each library file.

--localedir <locale directory>

The place where darktable finds its language specific text strings. The default place depends on your installation. Typical places are /opt/darktable/share/locale/ and /usr/share/locale/.

--luacmd <lua command>

A string containing lua commands to execute after lua initialization. These commands will be run after your luarc file.

If lua is not compiled in, this option will be accepted but won't do anything.

--noiseprofiles <noiseprofiles json file>

The json file that contains the camera specific noise profiles. The default location depends on your installation. Typical places are /opt/darktable/share/darktable/noiseprofile.json and /usr/share/darktable/noiseprofile.json.

--conf <key>=<value>

darktable supports a rich set of configuration parameters which the user defines in darktablerc – darktable's configuration file in the user config directory. You may temporarily overwrite individual settings on the command line with this option – however, these settings will not be stored in darktablerc.

1.1.2. darktable-cli binary

This binary starts the command line interface variant of darktable which allows exporting images.

This variant does not open any display, so it will work in pure console mode without using any X11, wayland, etc. – this mode is useful for servers running background jobs.

darktable-cli is called with the following command line parameters:

darktable-cli <input file>|<image folder>
              [<xmp file>]
              <output file>
              [--width <max width>]
              [--height <max height>]
              [--bpp <bpp>]
              [--hq <0|1|true|false>]
              [--verbose]
              [--core <darktable options>]

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

<input file>

The name of the input file to export or the name of an folder containing input images which are to be exported.

<xmp file>

The optional name of an XMP sidecar file containing the history stack data to be applied during export. If this option is not given darktable will search for an XMP file that belongs to the given input file(s).

<output file>

The name of the output file. darktable derives the export file format from the file extension. You can also use all the variables available in darktable's export module in the output filename (see Section 2.3.12, “Export selected”). For obvious reasons this is mandatory if you use the program on an image folder containing multiple images.

--width <max width>

This optional parameter allows to limit the width of the exported image to that number of pixels.

--height <max height>

This optional parameter allows to limit the height of the exported image to that number of pixels.

--bpp <bpp>

An optional parameter to define the bit depth of the exported image; allowed values depend on the file format. Currently this option is not yet functional. If you need to define the bit depth you need to use the following workaround:

--core
--conf plugins/imageio/format/<FORMAT>/bpp=<VALUE>

where <FORMAT> is the name of the selected output format.

--hq <0|1|true|false>

A flag that defines whether to use high quality resampling during export (see Section 8.2, “Core options”). Defaults to true.

--verbose

Enables verbose output.

--core <darktable options>

All command line parameters following --core are passed to the darktable core and handled as standard parameters. See Section 1.1.1, “darktable binary” for a detailed description.

1.1.3. darktable-generate-cache binary

This binary updates darktable's thumbnail cache. You can start this program to generate all missing thumbnails in the background when your computer is idle.

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

darktable-generate-cache
              [-h, --help]
              [--version]
              [--min-mip <0-7>] [-m, --max-mip <0 - 7>]
              [--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

Gives usage information and terminates.

--version

Gives copyright and version information and terminates.

--min-mip <0 - 7>, -m, --max-mip <0 - 7>

darktable can handle and store thumbnails with up to eight different resolution steps for each image. These parameters define which maximum resolution should be generated and default 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 from the entire collection.

--core <darktable options>

All command line parameters following --core are passed to the darktable core and handled as standard parameters. See Section 1.1.1, “darktable binary” for a detailed description.

1.1.4. darktable-chart binary

This 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 Section 10.3, “Using darktable-chart.

darktable-chart either starts a GUI or is 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 etc. Starting darktable-chart this way opens a special GUI (details can be found in Section 10.3, “Using darktable-chart).

--help

Gives usage information and terminates.

<input Lab pfm file>

Opens the utility with the given file as source image. The input file needs to be in Lab Portable Float Map format.

<cht file>

Specifies a chart file describing the layout of the used color reference chart.

<reference cgats/it8 or Lab pfm file>

Specifies the reference values, either as measured values according to the CGATS standard, or as a reference image in Lab Portable Float Map format.

Alternatively darktable-chart can be used as a command line program to generate darktable style files out of previously saved CSV files.

darktable-chart
              --csv
              <csv file> 
              <number patches> 
              <output dtstyle file>

All parameters are mandatory.

<csv file>

A CSV file previously saved from within darktable-chart.

<number patches>

The number of color patches to be used in the color look up table settings of the created style.

<output dtstyle file>

The name of the style file to be created.

1.1.5. darktable-cltest binary

This 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-cltest

1.1.6. darktable-cmstest binary

This binary investigates if the color management subsystem of your computer is correctly configured and it displays some useful information about the installed monitor profile(s).

darktable-cmstest is called without command line parameters:

darktable-cmstest