basic principles
Scripts can register callbacks to perform actions on various darktable events. This callback mechanism is the primary method of triggering lua actions.
The central orchestrator for lua scripts is the script manager, which spawns the utility module scripts in the lighttable and loads darktable’s bundled scripts.
Lua scripts can be disabled in preferences/lua options.
🔗how darktable loads scripts (and the script manager)
darktable treats two kinds of location differently: Files that are executed as Lua code, and directories that are scanned for scripts:
- Executed at startup:
$DARKTABLE/share/darktable/luarc: run by darktable itself. This is the entry point that launches the script manager. It serves internal purposes only and should not be edited. $DARKTABLE is the program’s installation directory.[configuration-directory]/luarc: run by the script manager, if present. This is one way of running your own scripts (see below).
- Scanned for
.luascripts (which then appear in the scripts-module):$DARKTABLE/share/darktable/lua-scripts/: darktable’s bundled scripts.[configuration-directory]/lua/[folder]: your own scripts (see below).
The configuration directory is specific to your OS.
Thus you can add your own scripts as follows:
- Have the scripts-module pick them up: (recommended)
- Place your script e.g. in
[configuration-directory]/lua/user/myscript.lua - Activate it in the scripts-module by selecting the appropriate folder (in this example “user”) and clicking the on/off button next to the corresponding script.
- Note: For the scripts-module to pick up scripts they will need to be in a subfolder of
configuration-directory/lua.
- Place your script e.g. in
- Use
luarc(runs at startup automatically)- Either write the code directly into
[configuration-directory]/luarc. This works, but is not practical for anything beyond a few lines. - Or keep the code in its own file and
requirethroughluarc: E.g. a script present in[configuration-directory]/lua/userscript.luacould be loaded by addingrequire "userscript"(note that .lua is omitted here).
- Either write the code directly into
🔗a note on lua-scripts installations from previous darktable versions
Before version 5.6 darktable’s scripts had to be installed manually (see darktable’s scripts).
To remain compatible with such an installation, require looks for a script manager in your configuration directory before loading the bundled one: if [configuration-directory]/lua/tools/script_manager.lua is present (for example from a manual pre-5.6 installation), that script manager is run instead of the bundled one. In this case the luarc file in the configuration directory is not loaded.