Preferences & Settings on darktable 5.6 user manual

overview

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

darktable comes with a number of user-configurable preferences. These can be adjusted in the preferences dialog, which can be reached by clicking the gear icon on the right of the top panel. Preferences are separated into tabs, each of which is described in more detail in the following sections.

When opened from within the lighttable or darkroom views, the appropriate tab will be loaded by default to allow you to modify that view’s settings.

backup settings & edits

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

If you want to back up darktable’s settings and edits you can save a copy of the contents of the configuration directory. See configuration directory for descriptions of what the individual files contain.

Transferring the contents of this directory also allows for migration between variants (e.g. between Flatpak and AppImage) of darktable.

Darktable also maintains a number of backups of data.db and library.db inside the configuration directory: 15 daily snapshots of each, plus a snapshot created when updating to a new version (e.g. data.db-pre-5.4.1).

general

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

Control the overall look and feel of darktable.

interface language: Set the language of the user interface. This includes the option to enable sentence case (en@truecase) for English. The system default is marked with an * (needs a restart)
theme: Set the theme for the user interface. Aside from any aesthetic considerations, the recommended interface color for color evaluation is middle gray. Visual perception is affected by ambient brightness, and a low user interface brightness causes all kinds of illusions. Using a dark interface to retouch photos can therefore lead to excessive retouching (abuse of contrast and saturation) and to a photo that is too dark when printed. It is therefore highly recommended that you use one of the “grey” themes for retouching work as these are designed so that the user interface approximates middle gray. For those who have difficulty reading text in the default theme, darktable includes two “highcontrast” themes with white text on a dark background, but the caveats mentioned previously apply if you select one of them (default “darktable-elegant-grey”).
use system font size: Select this option to use the font size defined by your system. If unchecked, you may enter a custom font size in the box below (default on).
font size in points: If the “use system font size” option is switched off, enter a font size (in points) for darktable to use. The font size will be changed immediately.
GUI controls and text DPI: Adjust the global GUI resolution to rescale controls, buttons, labels, etc. Increase for a magnified GUI, decrease to fit more content in the window. Set to -1 to use the system-defined global resolution. The default is 96 DPI on most systems. (needs a restart)
reset view panels: The order and visibility of utility modules can be manually changed by the user (see modules overview). Click this button to reset to default values.

🔗CSS theme modifications

In addition to selecting a pre-built theme you can also apply additional CSS customizations of your own to tweak the look-and-feel of darktable.

import

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

Control default file naming conventions used when importing images.

🔗session options

The following options define the default naming pattern for use in the “copy & import” or “copy & import from camera” options in the import module, or when taking photos in the tethering view.

The naming pattern consists of three parts: a base part defining the parent folder, a session part defining a filmroll (which is specific to the individual import session), and a file name part defining the filename structure for each imported image.

lighttable

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

Control functionality in the lighttable view and modules.

🔗general

hide built-in presets for utility modules: If enabled, only user-defined presets will be shown in presets menu for utility modules – built-in presets will be hidden (default off).
use single-click in the collections module: Enable “single click” mode in the collections module, which allows ranges to be selected (default off).
prioritize the hovered image over the selected images: Controls which images are affected by an action (e.g. using the keyboard to set the number of stars). If this option is enabled, only the image hovered over is affected by the action. If disabled, all the selected images are affected (i.e. selection is prioritized) and the hovered-over image is only affected if it is also one of the selected images. (default on)
expand a single utility module at a time: Controls how utility modules are expanded. If this option is enabled, expanding a module by clicking collapses any other currently expanded panel. If you want to expand a panel without collapsing the others you can do so with Shift+click. Disabling this option inverts the meaning of click and Shift+click (default off).
scroll utility modules to the top when expanded: With this option enabled the side panerepresent will scroll a utility module to the top of the panel when it is expanded. (default off)
rating an image one star twice will not zero out the rating: Normally clicking a one star rating twice will set a zero star rating to that image. Check this option to disable this functionality (default off).
show scrollbars for center view: Choose whether to show scrollbars in the center view of the lighttable (default on).
show image time with milliseconds: Choose whether to include milliseconds when displaying time values (default off). If set, milliseconds are shown in the image information module and can also be used in the geotagging module.

🔗thumbnails

use raw file instead of embedded JPEG from size: When generating thumbnails for images that have not yet been processed in the darkroom, if the thumbnail size is greater than this value, generate it by processing the raw image data. If the thumbnail is below this size, use the JPEG preview image embedded in the raw file. Once an image has been processed in the darkroom, thumbnails will always be generated from raw data (you can revert back to the JPEG preview by discarding history). To render thumbnails with the best quality choose “always”.
high quality processing from size: If the thumbnail size is greater than this value and is being generated from raw data, it will be processed using the full quality rendering path, which is better but slower (default 720p). To render thumbnails with the best quality, choose “always”.
enable disk backend for thumbnail cache: If activated, darktable stores all thumbnails on disk as a secondary cache, and thereby keeps thumbnails accessible if they are dropped from the primary cache. This needs more disk space but speeds up the lighttable view as it avoids the reprocessing of thumbnails (default on).
enable disk backend for full preview cache: If enabled, darktable writes full preview images to disk (.cache/darktable/) when evicted from the memory cache. Note that this can take a lot of storage (several gigabytes for 20k images) and darktable will never delete cached images. It’s safe to delete these manually if you want. Enabling this option will greatly improve lighttable performance when zooming an image in full preview mode (default off).
enable smooth scrolling for lighttable thumbnails: If enabled, use fractional scrolling when navigating through the thumbnails in the filemanager layout for a smoother experience. When enabled, the top row of thumbnails may only show partial images as the scrolling is not aligned with each row. This setting is most useful when scrolling via a touchpad or other input device rather than a mouse with a scroll wheel (default off).
generate thumbnails in background: Choose whether to automatically generate thumbnails in the background when the user is in the lighttable view and is inactive (no keyboard/mouse activity). Thumbnails will be generated up to the selected size (default never).; Note: You can set the period of inactivity required before thumbnail generation will start by altering the backthumbs_inactivity setting in darktablerc in the darktable configuration directory (default 5 seconds).

darkroom

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

Control functionality in the darkroom view and associated modules.

🔗general

scroll down to increase mask parameters: By default, scrolling your mouse up increases the value of the relevant shape parameters in drawn masks. Set this preference to reverse the behavior (default off).
middle mouse button zooms to 200%: When enabled, clicking the middle mouse button on the image canvas causes the zoom level to toggle between fit, 100% and 200%. When disabled, the middle mouse button toggles between fit and 100%. In the latter case, you can use Ctrl+middle-click to access the 200% zoom level (default on).
pattern for the image information line: Set the information to be displayed in the image information line. You can use any variables in the variables section as well as $(NL) for a new line. You can also include formatting (bold, italic, colors etc).
position of the image information line: Choose the darkroom panel in which the image information line is displayed. Choose between “top left” “top right” “top center” “bottom” and “hidden” (default “bottom”).
border around image in darkroom mode: Display the center image in darkroom mode with an outside border of the given number of pixels (default 20).
show scrollbars for center view: Choose whether to show scrollbars in the center view of the darkroom (default off).
show loading screen between images: Show gray loading screen when navigating between images in the darkroom. Switch this option off to just show a simple toast message and leave the previous image in place until the next image is loaded. Note that switching this option off can be very useful to quickly compare duplicate images, however, there might be issues with long loading times (leading you to think the next image has already loaded) and you may observe visual artifacts while the next image is loading (default on).

🔗modules

display of individual color channels

Control how individual color channels are displayed when activated in the parametric masks feature. You can choose between “false color” and “gray scale” (default “false color”).

hide built-in presets for processing modules

If enabled, only user-defined presets will be shown in the presets menu for processing modules – built-in presets will be hidden (default off).

show the guides widget in modules UI

Enable this to show the local guides & overlays interface directly within the UI of the modules that support it (default on).

expand a single processing module at a time

Control how processing modules are expanded in the darkroom. If this option is enabled, expanding a module by clicking collapses any currently expanded module. If you want to expand a module without collapsing the others you can do so with Shift+click. Disabling this option inverts the meaning of click and Shift+click (default on).

only collapse modules in current group

When choosing to expand a single processing module at a time (using the logic defined in the previous setting), only collapse other modules that appear in the current visible group. Disable this option to ensure that modules in non-visible groups are also collapsed (default on).

expand the module when it is activated, and collapse it when disabled

Select this option for the darkroom to automatically expand or collapse processing modules when they are enabled or disabled. (default off)

scroll processing modules to the top when expanded

With this option enabled processing modules are scrolled to the top of the right-hand panel when expanded. (default on)

swap the utility and processing modules panels

If enabled, swap the left and right side panels in the darkroom view (default off).

show right-side buttons in processing module headers

Choose whether to show the four buttons (mask indicator, multi-instance menu, reset, presets menu) on the right-hand-side of the module header for processing modules. These buttons will always appear when the mouse is over the module. At other times they will be shown or hidden according to this preference selection:

always: always show all buttons

active: only show the buttons when the mouse is over the module

dim: buttons are dimmed when mouse is not over the module

auto: hide the buttons when the panel is narrow

fade: fade out all buttons when the panel narrows

fit: hide all the buttons if the module name doesn’t fit

smooth: fade out all buttons in one header simultaneously

glide: gradually hide individual buttons as needed

(default always)

show mask indicator in module headers

If enabled, an icon will be shown in the header of any processing modules that have a mask applied (default on).

prompt for name on addition of new instance

If enabled, when creating a new instance of a processing module, a prompt will be immediately displayed allowing you to set a name for the new instance (default off).

automatically update module name

Automatically update the name (label) on processing modules if the current parameters of the module match those of a saved preset. The module name will only be updated if it hasn’t already been manually amended for the current image. It will be set either to the module name from which the preset was made (if the module name was manually adjusted before the preset was created) or to the name of the preset itself (default on).

processing

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

Control how images are processed.

🔗image processing

always use LittleCMS 2 to apply output color profile: If this option is activated, darktable will use the LittleCMS 2 system library to apply the output color profile instead of its own internal routines. This is significantly slower than the default but might give more accurate results in some cases.; If the given ICC is LUT-based or contains both a LUT and a matrix, darktable will use LittleCMS 2 to render the colors regardless of this parameter’s value (default off).

security

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

Control whether warning messages are shown before undertaking certain activities.

🔗general

ask before removing images from the library: Always ask before removing image information from darktable’s library database, where the xmp file is retained (default on).
ask before deleting images from disk: Always ask before deleting an image file (default on).
ask before discarding history stack: Always ask before discarding the history stack of an image (default on).
try to use trash when deleting images: Instead of physically deleting images from disk, attempt to put them into the system’s trash bin (default on).
ask before moving images from film roll folder: Always ask before moving an image file (default on).
ask before copying images to new film roll folder: Always ask before copying an image file to a new location (default on).
ask before removing empty folders: Always ask before removing any empty folder. This can happen after moving or deleting images (default off).
ask before deleting a tag: Always ask before deleting a tag from an image (default on).
ask before deleting a style: Always ask before deleting a style (default on).
ask before deleting a preset: Always ask before deleting a preset (default on).
ask before exporting in overwrite mode: Always ask before exporting images in overwrite mode.

🔗other

password storage backend to use: The backend to use for password storage. Options: “auto” (default), “none”, “libsecret”, “kwallet”, “apple_keychain” (on macOS), “windows_credentials” (on Windows).
auto login to storage server: When exporting images to an external storage server (Piwigo) select this option to automatically log in to the server. You must set a password storage backend (above) to use this option.
executable for playing audio files: Define an external program which is used in the lighttable view to play audio files that some cameras record to keep notes for images (default “aplay”).

storage

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

The following options are related to darktable’s library database and XMP sidecar files.

🔗database

allow for multiple workspaces: Allows for multiple workspaces that can be selected via a popup window at startup. In the popup, it is possible to create a new workspace, delete workspaces, set a workspace as the default (used on startup until changed again), or to work from memory (no database). If remember selection and don’t ask again is checked when confirming a workspace, that selection is kept for the next launch without showing the popup, and allow for multiple workspaces is turned off so the popup stays hidden until you enable allow for multiple workspaces again here. A workspace is a combination of a library database and a darktablerc configuration file using the same shared configuration folder settings (data database and shortcuts). New workspaces can optionally be created by copying an existing workspace as a template; workspace-specific configuration is duplicated while paths, labels, collection history and similar keys are cleared so the new workspace keeps its own library database. See darktable invocation for more details around library.db, data.db and darktablerc. (default off)
create database snapshot: Specifies how often darktable should create database snapshots. Options are “never”, “once a month”, “once a week”, “once a day” and “on close” (default “once a week”)
how many snapshots to keep: Number of snapshots to keep after creating a new snapshot, not counting database backups taken when moving between darktable versions. Enter “-1” to store an unlimited number of snapshots. (default 10)

🔗XMP sidecar files

create XMP files

XMP sidecar files provide a redundant method of saving the changes that you have made to an image, in addition to the changes saved to darktable’s database. This option allows you to choose when files will first be written. Once written, they will subsequently be updated each time you edit or add a tag to the image. Choose from:

never: Don’t write sidecar files. This can be useful if you are running multiple version of darktable for development/testing purposes but is not normally recommended,

on import: A sidecar file will be written as soon as you add an image to darktable’s library,

after edit: A sidecar will not be written until the first time you edit or add a tag to an image.

It’s strongly recommended that you choose either “on import” or “after edit”. Sidecar files provide a useful fail-safe to prevent data loss if your database becomes corrupted. Backing up your raw file plus the accompanying sidecar file will allow you to fully restore your work at a later date by re-importing your edit history back into darktable (default “on import”).

miscellaneous

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

🔗interface

show splash screen at startup: When activated, darktable will display a splash screen indicating progress loading and initializing its code and data and scanning for updated sidecars until it is ready to display its main window. When disabled, darktable displays nothing until loading is complete and it can display the lighttable – or darkrooom, if invoked with a single filename on the command line (default on).
show welcome screen on next run: When activated, the Welcome setup pages will be shown the next time darktable is started (default on, but is set to off after the welcome pages are shown).
load default shortcuts at startup: When launching the application, darktable loads default shortcuts first, and then loads user-defined shortcuts on top. This allows default shortcuts to be overridden with a new action but prevents them from being deleted (since the deleted shortcut will be automatically reloaded on the next restart). Deactivate this preference to stop loading default shortcuts on startup – only load the user-defined ones (including any defaults that you have not subsequently deleted or overridden). This makes deletion easier but also means that you will not benefit from new shortcuts added in future versions without first re-enabling this preference (default on).
scale slider step with min/max: When activated, the default step-size, when altering sliders, will depend on the current min/max values for that slider (default on).
sort built-in presets first: Choose how the presets menu is sorted. If this option is enabled, built-in presets are shown first. If the option is disabled, user presets are shown first (default on).
mouse wheel scrolls modules side panel by default: When enabled, the mouse wheel scrolls side panels by default and Ctrl+Alt+wheel scrolls data entry fields. When disabled, this behavior is reversed (default off).
enable touchpad gestures in darkroom: When enabled, use two-finger touchpad gestures in darkroom for panning (two-finger touchpad scrolling) and pinch-to-zoom. When disabled, touchpad gestures are ignored and darkroom uses only the mouse scrolling behavior for zooming in and out (default on).
constrain darkroom zoom between screen fit and 100%: When enabled, limits scroll-wheel and pinch-to-zoom in the darkroom to the range between screen fit (zoom out) and 100% (zoom in). Hold Ctrl while zooming to temporarily lift the limit and zoom beyond 100%. When disabled, zoom is never constrained and the additional Ctrl key press is not needed to zoom beyond 100% (default on).
always show panels’ scrollbars: Defines whether the panel scrollbars should be always visible or activated only depending on the panel content (default on). (needs a restart)
duration of the ui transitions in ms: Defines how long modules and other ui elements will take to transition between states (expand/collapse). Set to 0 to disable animation (default 250ms).
position of the scopes module: Choose whether to show the scopes module in the left or right panel (default right). (needs a restart)
method to use for getting the display profile: This option allows the user to force darktable to use a specific method to obtain the current display profile for color management. In the default setting “all”, darktable will choose to query the X display server’s xatom or the colord system service. You can set this option to “xatom” or “colord” to enforce a specific method if the two methods give different results. You can run the darktable-cmstest binary to examine your color management subsystem.
order or exclude midi devices: Semicolon-separated list of device-name fragments. If matched, load the midi device at the id given by the location in the list. If preceded by “-”, prevent the matched device from loading. You can also add encoding and number of knobs. For example “BeatStep:63:16”. Please see midi device support for more information.

🔗tags

omit hierarchy in simple tag lists: When exporting images any hierarchical tags are also added as a simple list of non-hierarchical tags to make them visible to some other programs. When this option is checked darktable will only include the last part of the hierarchy and ignore the rest. So foo|bar|baz will only add baz.

🔗shortcuts with multiple instances

It is possible to create multiple instances of many processing modules. In this scenario it is not always obvious which instance should be controlled by keyboard shortcut operations. The following options control rules that are applied (in order) to decide which module instance keyboard shortcuts should be applied to.

shortcuts

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

Shortcuts are a way to control darktable using your keyboard, mouse, trackpad, or other input devices, such as MIDI and game controllers (as detailed in the midi device support section). They allow you to perform actions without interacting directly with a UI element.

An action is usually an operation that you might undertake using darktable’s point-and-click user interface. See common actions for a list of the most common ones. For example:

Increase, decrease or reset sliders
Scroll through dropdown lists
Enable, expand or focus modules
Click buttons
Switch between views

The recommended way to assign shortcuts to visual elements is the visual shortcut mapping mode.

presets

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

This menu provides an overview of the presets that are defined for darktable’s modules, and allows you to modify some of their properties.

Pre-defined presets (those that are included by default within darktable) are shown with a lock symbol. Their properties cannot be changed.

User-defined presets can be imported from exported .dtpreset files using the “import” button at the bottom of the screen. You can export all user-defined presets to a single directory using the “export” button.

AI

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

Control darktable’s AI features: enable or disable them, choose a hardware accelerator for model inference, point darktable at an ONNX Runtime library, and manage the AI models available on disk.

AI features are powered by ONNX Runtime. What runs out of the box and what GPU acceleration can be added on each platform:

OS	Bundled	Optional GPU acceleration
Linux	CPU only	NVIDIA CUDA, AMD ROCm/MIGraphX, Intel OpenVINO
Windows	DirectML (any DirectX 12 GPU)	NVIDIA CUDA, Intel OpenVINO
macOS	CoreML (Apple Silicon, integrated GPU)	–

Install scripts for the GPU runtimes are described below; see GPU acceleration for the full instructions.

lua options

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

🔗From 5.6 onward

These settings control how lua scripts are handled.

check for updated lua scripts on start up: automatically update (bundled) scripts to current version.
disable lua scripts: do not run lua scripts (bundled and user defined).

Note: If you have a previous lua scripts installation (e.g. Lua API 9.6.0 from darktable 5.4) in your configuration directory the option disable scripts will not be displayed. After (automatically) updating the scripts through the script manager the option will appear.

configuration directory

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

darktable stores its settings, presets, styles, library database, etc. in a default directory. This directory’s location depends on your operating system and installation method. It can be changed by using the --config-dir option (see darktable invocation).

Linux
- Installed via package manager or AppImage: $HOME/.config/darktable
- Flatpak: $HOME/.var/app/org.darktable.Darktable/config/darktable
- snap: $HOME/snap/darktable/current/
Windows: %LOCALAPPDATA%\darktable
- E.g. C:\Users\<username>\AppData\Local\darktable
macOS: $HOME/.config/darktable

🔗Notable files/folders:

lua (folder): Contains all lua scripts
styles (folder): User created styles
darktablerc: Main configuration file
data.db and library.db: Central libraries: Image File Locations, metadata, edits etc.
luarc: Defines Lua scripts to be loaded upon startup
shortcutsrc: Keyboard shortcut configuration
user.css: User-defined CSS-tweaks