Lua updates for darktable 3.6

darktable 3.6 is due to be released in the next few hours. Along with a host of new features there are also lots of changes to the lua scripting API enabling lots of new functionality.

The Good

  • New documentation. In addition to a new Lua API Manual, there is also a Lua Scripts Manual and a Lua Scripts API Manual located at darktable lua documentation - Home. A huge thanks to @paperdigits and @elstoc for helping make this happen.

  • Widget naming - widgets now have a name field, making it possible to style them using CSS. This makes it possible for script_manager to provide a color option to show whether a script is running or not. To set the colors the following CSS needs added in the preferences->general CSS tweaks section:
    button#sm_started label { color: rgb(50,210,50); }
    button#sm_stopped label { color: rgb(210,50,50); }


  • Starting and stopping scripts from script_manager. script_manager can now stop scripts and remove them from the UI thanks to the following changes:

    • darktable.gui.libs.visibility is fixed so that setting a lib to hidden (false) removes it from the user interface.

    • darktable.gui.libs.metadata_view.destroy_info() - function added to remove field added by darktable.gui.libs.metadata_view.register_info() from the image information display. Thanks @phweyland

    • Event naming - add a name field to darktable.register_event() so that multiple events of the same type can differentiated and the desired one selected and accessed.

    • Event destruction - added darktable.destroy_event() to remove an event.

    • Selection naming - add a name field to so that the selection button can be selected and manipulated after creation

    • Selection destruction - add to remove a selection button from the user interface.

    • Action naming - add a name field to darktable.gui.libs.image.register_action() so that the action button can be selected and manipulated after creation

    • Action destruction - add darktable.gui.libs.image.destroy_action() to remove a lua created action button from the user interface.

    • Storage removal - add darktable.destroy_storage() to remove a lua created storage from the exporter

  • Select and Action button sensitivity can be controlled so that the behavior matches the core buttons

    • Add selection-changed to the lua events so that scripts can respond when the selection changes

    • Selection sensitivity - add to set selection button sensitivity

    • Action sensitivity - add darktable.gui.libs.image.set_action_sensitive() to set action button sensitivity

  • Other

    • Password storage and retrieval - added and darktable.password.get() to save and retrieve passwords using the darktable password storage back end.

    • Preferences - added darktable.preferences.destroy() to remove a preference. Added darktable.preferences.get_keys() to return a sorted table of all of the preferences for both darktable and lua.

    • Get image from database by image id - added darktable.database.get_image() to retrieve an image by the image ID

    • Bugfix - Changed text_view widget to wrap lines when the text exceeds the width of the widget

    • Widget visibility - add visible member to widgets for visibility control

The Bad

All of the API breaking changes. Users need to update their lua-scripts after upgrading to darktable 3.6. This can be done from script_manager in the install/update section.

Any old scripts that use the following functions must be updated to be compatible with darktable 3.6

  • darktable.register_event()

  • darktable.gui.libs.image.register_action()


The Ugly

The way that I tried to handle the API breaking changes this past 6 months. I added lots of conditionals to the code trying to make trying to make it compatible with the existing API as well as the new API. It mostly worked, but was a nightmare to implement and maintain.

Going forward API changes will be handled as follows:

  • The current production API version will be the master branch of the repository

  • A development branch will be created for the next API version. This will allow testing of the new API without breaking production code.

  • Old API versions will each have their own branch. This allows back porting fixes and, in some cases, scripts to previous API versions.

  • script_manager is now API version aware and capable of using the correct version of the scripts for the API being used.


Thank you @wpferguson for all the work!


… hours ?


Somehow I don’t get the lua-scripts working on a clean darktable install on my windows 10. I use the installer and on the first startup after the installation, I can select to install the lua-scripts in the bottom left corner. After a restart, I would expect the script manager to appear in that lower-left corner but nothing is there.
In my user folder, the lua subfolder exists and the luarc has "require “tools/script_manager” " as the only entry. Does anyone have an idea what I am doing wrong? I had it working fine just a few days ago …

Can you open a command prompt and run the following command please?

"\Program Files\darktable\bin\darktable.exe" -d lua > log.txt

Please post the contents of the log.txt file



This is the output of the log file:

5,528015 LUA ERROR : …00_Exchange\XX_darktable_db/lua/tools/script_manager.lua:213: attempt to concatenate a nil value (local ‘branch’)

Note that I run darktable with --configdir …00_Exchange\XX_darktable_db/
Actually, when I run it in the default user folder it works fine :thinking: But I had it working in that user-defined folder before for sure.

Please open a command prompt and go to your …00_Exchange\XX_darktable_db/lua directory. Then run the command git status and please post the results.



Thanks, this gives the following:

$ git status
On branch master
Your branch is up to date with ‘origin/master’.

nothing to commit, working tree clean

I just tried to install lua scripts in actual master and can reproduce too. On Linux, I have that error when launching darktable with -d lua option:

0,958272 LUA ERROR : /home/nilvus/.config/darktable/lua/tools/script_manager.lua:213: attempt to concatenate a nil value (local ‘branch’). I always compile in master branch (git status is same as MeisterKaos)

I’ve checked my darktable config dir and I have luarc with line "require “tools/script_manager”

To reproduce:

  • don’t have lua installed but of course darktable compiled with support
  • launch darktable
  • execute installer to install lua scripts
  • wait a little to see lua scripts installed message shown
  • nothing else happen then
  • when relaunching darktable, see no lua scripts in darktable windows nor script installer

But luarc file and lua folder are there in darktable config dir.

I just pushed a possible fix. Go to your lua directory and do a git pull which should give you the fix. If it crashes, it should dump some data so I can see what’s going on.


1 Like

@wpferguson: I just found a way to fix that error (so probably some update not taken correctly when installing lua scripts).

I just go to configdir/darktable/lua folder and then make a git pull. Then I have that:

remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 5 (delta 3), reused 4 (delta 3), pack-reused 0
Dépaquetage des objets: 100% (5/5), 1.06 Kio | 362.00 Kio/s, fait.
   ecdc74b..c96c523  master     -> origin/master
Mise à jour ecdc74b..c96c523
 tools/script_manager.lua | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

Just posted same time, so that explain why that works. Just a good synchro :wink: ! Thanks for the quick fix.

Try running with -d lua and see if it spits out an error and dumps some data please

0,978626 LUA ERROR: script_manager.lua: get_current_repo_branch: 214: no branch detected in repo_data
Sur la branche master
Votre branche est à jour avec ‘origin/master’.

rien à valider, la copie de travail est propre

Another really great idea sabotaged by I18N :laughing:. Didn’t take translation into account when parsing the output. Time for a rethink…

Thanks for the effort! I expected it to be a problem on my side^^
Same output for me:

5,731021 LUA ERROR: script_manager.lua: get_current_repo_branch: 214: no branch detected in repo_data

But the script manager now appears as expected and i can load the gimp plugin for example. enfuseAdvanced on the other hand fails with the following message:

121,019851 LUA ERROR: script_manager.lua: activate: 334: Error loading contrib/enfuseAdvanced
121,019983 LUA ERROR: script_manager.lua: activate: 335: Error message: …_Exchange\XX_darktable_db/lua/contrib/enfuseAdvanced.lua:873: attempt to index a nil value (field ‘?’)

If I remember correctly I have to specify the enfuse, align_image_stack and exiftool location in the Lua-options menu, but only after I started the script. Now loading fails and I cannot choose anything in options.

You can start tools->executable_manager and specify them in there.

Hmm, in the executable manager I can only choose “git” as the executable to configure. Also enfuseAdvanced still fails to load. And I am very sure that there was a menu option before, right? Something still seems wrong :thinking: