ANSEL(1)

📦 version 0-unstable-2026-06, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

ansel — a digital photography workflow application. (yes that's the whole thing, she's concise 💅)

This is the ansel(1) manual page, in case you were wondering which darktable-adjacent queen you're reading about 🎀

✨ SYNOPSIS ✨

    ansel [options] [IMG_1234.{RAW,...}|image_folder/]

Options:

    --cachedir <user cache directory>
    --conf <key>=<value>
    --configdir <user config directory>
    -d {all,cache,camctl,camsupport,control,dev,fswatch,history,imageio,input,
        ioporder,lighttable,lua,masks,memory,nan,opencl,params,perf,pipe,
        pwstorage,print,signal,sql,undo}
    --datadir <data directory>
    --disable-opencl
    -h, --help
    --library <library file>
    --localedir <locale directory>
    --luacmd <lua command>
    --moduledir <module directory>
    --noiseprofiles <noiseprofiles json file>
    -t <num openmp threads>
    --tmpdir <tmp directory>
    --version

💜 DESCRIPTION 💜

okay so ansel is a digital photography workflow application for Linux, Mac OS X and several other Unices. literally all the Unixes, she's inclusive 🦋

The whole point of her is to make editing and consistent processing of big photo sessions easy — like, huge sessions, hundreds of shots — and she gives you an easy-to-use digital lighttable plus a whole set of sophisticated post-processing tools. it's giving full studio in one app 👑

Most processing happens in 32-bit floating point per channel mode, in the device independent CIE L*a*b* color space. and she's fully color managed too, which means you get full control over the look of your photos. no cap, your colors are yours 🌈

She also runs on a modern plugin architecture, so it's super easy for 3rd party developers to extend what she can already do. every single lighttable and darkroom feature is implemented as a plugin — so you can write your own plugins by reusing existing code, iconic behavior honestly. and most workflow-specific things can be scripted in Lua too 🧚

🎀 OPTIONS 🎀

  • IMG_1234.RAW or image_folder/ — bestie, you can optionally hand her the filename of an image, or the name of a folder full of images. give her a filename and ansel starts up in darkroom view with that file already open. give her a folder and she starts in lighttable view with that folder's contents as the current collection. and if there's already an ansel instance running (using the same library), the image or folder gets opened over there instead — the two processes talk to each other over D-Bus 🫶
  • --cachedir <cache directory> — ansel keeps a cache of image thumbnails for fast image preview, plus precompiled OpenCL binaries for fast startup. by default the cache lives in "$HOME/.cache/darktable/". fun fact: there can be multiple thumbnail caches chillin' in parallel — one for each library file 💅
  • --conf <key>=<value> — she supports a rich set of configuration parameters, which you define in "anselrc" — that's ansel's config file, living in the user config directory. this option lets you temporarily overwrite individual settings right on the command line. BUT — and this is the important bit — those settings will not be stored in "anselrc". temporary means temporary, bestie 🙈
  • --configdir <config directory> — sets the directory where ansel stores your user-specific configuration. the default place is "$HOME/.config/darktable/" ✨
  • -d <debug option> — turns on debug output to the terminal. ansel has several subsystems and you can activate debugging for each one separately. you can use this option multiple times if you want debug output from more than one subsystem 🔍

A few of those debug options are:

  • control — enable job queue debugging. if you redirect ansel's output to control.log and call ./tools/create_control_svg.sh control.log, you get a cute little control.svg visualizing the threads' work 🎀
  • cache — gives you a lot of debugging info about the thumbnail cache for lighttable mode. and if she's compiled in debug mode, this also tells you where in the code a certain buffer was last locked 👀
  • perf — use this for performance tweaking your darkroom modules. it'll rdtsc-measure the runtimes of all plugins and print them to stdout. numbers go brrr 🔥
  • all — enable all debugging output. in general this is not very useful, so like... proceed with caution 💀
  • --datadir <data directory> — defines the directory where ansel finds her runtime data. the default place depends on your installation. typical places are "/opt/ansel/share/darktable/" and "/usr/share/darktable/" 🦋
  • --disable-opencl — stops ansel from initializing the OpenCL subsystem. use this one if ansel crashes at startup because of a defective OpenCL implementation. she's not being dramatic, the OpenCL is just broken 😭
  • -h, --help — show the available command line options and exit. the classic "what are my choices" moment 👑
  • --library <library file> — ansel keeps image information in an sqlite database for fast access. the default location of that database file is "$HOME/.config/darktable/library.db". you can give an alternative location, e.g. if you want to do some experiments without compromising your original library.db. if the database file doesn't exist, ansel creates it for you 🫶 you can also pass ":memory:" as the library file — in that case the database is kept in system memory, and all changes are discarded when ansel terminates. poof. gone. so don't do real work in there 💀
  • --localedir <locale directory> — the place where ansel finds her language-specific text strings. default depends on your installation; typical places are "/opt/ansel/share/locale/" and "/usr/share/locale/" 🌍
  • --luacmd <lua command> — a string containing lua commands to execute after lua initialization. these commands run after your "luarc" file. and ngl, if lua isn't compiled in, this option will still be accepted but won't do anything 🫠
  • --moduledir <module directory> — ansel has a modular structure and organizes her modules as shared libraries for loading at runtime. with this option you tell her where to look for those shared libraries. the default place depends on your installation; typical places are "/opt/ansel/lib/darktable/" and "/usr/lib/darktable/" 🧚
  • --noiseprofiles <noiseprofiles json file> — ansel's profiled denoise module uses camera-specific profile data loaded from an external JSON file. with this option you can change which file gets loaded, so you can test alternative profiles. the default profile file is "noiseprofiles.json" and it's typically found in "/opt/ansel/share/darktable/" or "/usr/share/darktable/" 📸
  • -t <num openmp threads> — ansel uses OpenMP to parallelize a ton of computation steps and use all your available CPU cores. this option specifies the number of threads to use. valid values are between 1 and 100. that's the range, bestie, stay in it 🔥
  • --tmpdir <tmp directory> — the place where ansel stores her temporary files. if you don't supply this option, she just uses the system default ✨
  • --version — show the ansel version along with some important build options and exit. a little resume moment 👑

🌈 DEFAULT KEYBINDINGS 🌈

💫 All modes

  • l — switch to lighttable view
  • d — switch to darkroom view
  • t — switch to tethered capture view
  • m — switch to map view
  • s — switch to slideshow view
  • p — switch to print view
  • . — switch between lighttable and darkroom views
  • Ctrl+q — quit
  • F11 — switch between fullscreen and normal modes of the application's window
  • Esc — leave fullscreen mode
  • Ctrl+h — show/hide header
  • Tab — show/hide sidebars

🌸 Lighttable mode

  • g, Shift-g — navigate to top, bottom row
  • PageUp, PageDown — navigate one page up, down
  • ' — scroll center
  • Down, Left, Right, Up — scroll down, left, right, up
  • z — preview image
  • Ctrl+z — preview image with focus detection
  • F1, F2, F3, F4, F5 — color labels: toggle red, yellow, green, blue and purple
  • 1, 2, 3, 4, 5 — star rating
  • 0 — strip all stars
  • r — mark as rejected
  • l — realign images to the grid
  • Alt-1 — zoom in on first visible image
  • Alt-2, 3 — adjust zoom
  • Alt-4 — zoom out completely
  • Ctrl+a — select all images
  • Ctrl+Shift+a — select no images
  • Ctrl+i — invert selection
  • Ctrl+d — duplicate image
  • Ctrl+g, Ctrl+Shift+g — group/ungroup selected images
  • Delete — remove image from collection
  • Ctrl+c, Ctrl+Shift+c — copy all, selected history
  • Ctrl+v, Ctrl+Shift+v — paste all, selected history
  • Space — toggle selection of an image
  • Return — select an image
  • Ctrl+e — export currently selected images
  • Ctrl+k — jump back to the previous collection
  • Ctrl+t — open a popup to quickly tag an image
  • Ctrl+Shift+i — import a folder
  • Ctrl+j — jump to the filmroll of an image

🦋 Darkroom mode

  • Alt-1, 2, 3 — zoom to 1:1, fill, and fit, respectively
  • Ctrl+f — show/hide filmstrip
  • Space, Backspace — step to next, previous image
  • Ctrl+e — export current image
  • Ctrl+c, Ctrl+Shift+c — copy all, selected history
  • Ctrl+v, Ctrl+Shift+v — paste all, selected history
  • o — toggle show of over- and under-exposure
  • Ctrl+g — toggle gamut check
  • Ctrl+s — toggle softproofing
  • Enter — in Crop & Rotate module, commit the crop
  • [, ] — in Flip module, rotate 90 degrees ccw, cw
  • <, > — when drawing masks, decrease, increase brush opacity, respectively
  • {, } — when drawing masks, decrease, increase brush hardness, respectively
  • [, ] — when drawing masks, decrease, increase brush size, respectively

🧚 Tethered mode

  • Ctrl+f — show/hide filmstrip
  • v — toggle live view

🗺️ Map mode

  • Ctrl+f — show/hide filmstrip
  • Ctrl+z — undo
  • Ctrl+r — redo

🎞️ Filmstrip (when the cursor is on top of the filmstrip)

  • F1, F2, F3, F4, F5 — color labels: toggle red, yellow, green, blue and purple
  • 1, 2, 3, 4, 5 — star rating
  • 0 — strip all stars
  • r — mark as rejected
  • Ctrl+d — duplicate image
  • Ctrl+a — select all images
  • Ctrl+Shift+a — select no images
  • Ctrl+i — invert selection
  • Ctrl+c, Ctrl+Shift+c — copy all, selected history
  • Ctrl+v, Ctrl+Shift+v — paste all, selected history

🍓 Slideshow mode

  • Space — start/stop playback

🫶 SEE ALSO 🫶

ansel-cli(1) — go read that one too, bestie, iykyk 💖

🎀 OTHER INFO 🎀

okay so if you're nosy like me and want the ~lore~, bestie, the website is right here — news, blog, bug tracker, the whole vibe:

<https://www.darktable.org/>

and for the full manual, the complete ansel usermanual lives at:

<https://www.darktable.org/usermanual/>

there's also anselrc.html, which is a full overview of all the default config settings 💅 where it lives depends on your install, but the typical spots are:

  • "/opt/ansel/share/doc/darktable/"
  • "/usr/share/doc/darktable/"

so yeah, go look there. it's giving documentation treasure hunt 🗺️✨

💀 REPORTING BUGS 💀

found a bug? have a feature request? just wanna yell? please use the bug tracker at:

<https://github.com/ansel-org/darktable/issues>

that's the spot for bugs, feature requests "and so on" — their words, not mine 😌🫶

👑 AUTHORS 👑

the principal developer of ansel is Johannes Hanika 🌟 and here's the (hopefully) complete list of contributors to the project — and yes, the sub-lists are literally empty in the source, that's not me skipping anything, that's just how it be 😭:

  • developers:
  • translators:
  • contributors (at least 4 commits):
  • Sub-module rawspeed contributors (at least 1 commit):
  • Sub-module OpenCL contributors (at least 1 commit):
  • Sub-module whereami contributors (at least 1 commit):
  • Sub-module LibRaw contributors (at least 1 commit):
  • Sub-module doxygen-awesome-css contributors (at least 1 commit):

And all those of you that made previous releases possible 💖 (that's the sweetest line on the whole page ngl)

also, credit where credit is due — this man page was written by Alexandre Prokoudine <alexandre.prokoudine@gmail.com> and Richard Levitte <richard@levittr.org>. Additions were made by Tobias Ellinghaus <me@houz.org>. icons 🫡

🌸 HISTORY 🌸

the project was started by Johannes Hanika in early 2009, and the reason is honestly iconic: to fill the gap — or, rather, a black hole 🕳️ — of a digital photography workflow tool on Linux. like, nothing existed, so he made one. main character energy fr fr ✨

Copyright (C) 2009-2017 by Authors.

ansel is free software; you can redistribute it and/or modify it under the terms of the GPL v3 or (at your option) any later version 🔥

💅 and that's the whole page, bestie. go forth, read raw files, edit responsibly.

okay so this was darktable 2.3, dated 2017-01-20, filed under ANSEL(1) — and that's a wrap, mwah 🎀💜🦋

📦 where this page comes from