using Lua scripts
Table of Contents
#overview
darktable can execute scripts written in Lua to perform an extensive array of actions. Some examples include calling external applications (e.g. after exporting an image), creating keyboard shortcuts that trigger multiple actions in one keystroke, or building entire utility modules.
darktable comes with a number of scripts included. The central orchestrator for scripts is the utility module scripts available in the lighttable. Before darktable 5.6 scripts had to be installed first.
The comprehensive documentation on Lua scripting in darktable can be found in the darktable lua documentation. For a detailed introduction into the Lua language itself, see the Lua reference manual.
#enabling scripts
darktable (starting at version 5.6) comes with several built-in and contributed scripts for performing various actions.
To use a supplied script, you first must enable it. In this example we will enable the script rename-images which will spawn a utility module in the lighttable.
- Make sure scripts are enabled in preferences > lua.
- Identify in which folder the script you want to enable lives. An overview of all scripts is available in darktable’s lua documentation. In our example rename-images is contained in the folder contributed.
- Find the scripts module in the lower left corner of the lighttable view and expand it.
- Select the action: start/stop scripts from the dropdown.
- Under scripts select the appropriate folder from the dropdown (in our example contributed).
- Find the script you want to enable by using the arrows to flip through the pages. In our example, rename-images is (as of this writing) on the last page.
- Click the grayed-out start/stop icon to the left of the script’s name to start it. The icon should turn white and the script’s user interface (if it has one) will appear in a panel in the appropriate view. In this example, an additional utility module rename images will appear in the lighttable’s right panel.
#using custom scripts
If you want to use custom scripts it is recommended to place them inside the configuration directory into lua/<name>/. Replace <name> with a string of your liking, e.g. user. darktable will pick up those folders and offer the included scripts to be enabled by selecting the corresponding folder within the scripts module. More information on how darktable loads scripts is availabe in the programmers guide.
#installing and updating scripts
Only relevant for darktable versions pre 5.6, where the scripts were not bundled and had to be installed using the following instructions.
#download and install
The collection of scripts is available in the lua-scripts repository. This also includes the script manager, which makes it easier to enable or disable individual scripts from the GUI.
darktable should be started at least once to set up its directories. The config directories for most installation types are listed on the configuration directory page.
For most installation types (Linux package, AppImage, Flatpak, macOS and Windows) the Lua scripts can be installed from within darktable. First ensure git is installed on your system; if it isn’t, use the package manager to install it. Then, in the lighttable view, expand the lua scripts installer module in the lower-left corner, ensure that select action: install scripts is selected, and click execute. Restart darktable once for the scripts module to appear in the lower-left corner.
Some platforms need extra or alternative steps:
Linux Snap Packages
Installation through darktable’s GUI is currently broken, so you will have to take the following approach. Download the Lua scripts using git, then create the luarc to let darktable load the script-manager. Close darktable, open a terminal and:
cd ~/snap/darktable/current
git clone https://github.com/darktable-org/lua-scripts.git lua
echo 'require "tools/script_manager"' >> luarc
Restart darktable twice, and the scripts module should appear in the lower-left corner.
macOS
Alternatively you could use the console:
cd ~/.config/darktable/
git clone https://github.com/darktable-org/lua-scripts.git lua
Windows
Git can be obtained from git for windows, or using Windows package manager winget inside a command prompt with winget install git.git. If you use the gitforwindows.org distribution, install the Git Bash Shell also as it will aid in debugging the scripts if necessary.
#updating
To update the script repository, either use the scripts module GUI or open a terminal or command prompt and run the following commands:
Snap
cd ~/snap/darktable/current/lua
git pull
Flatpak
cd ~/.var/app/org.darktable.Darktable/config/darktable/lua
git pull
Linux and MacOS
cd ~/.config/darktable/lua/
git pull
Windows
cd %LOCALAPPDATA%\darktable\lua
git pull