Lua scripts in Darktable. How to?



Hello everyone!

I see people talking about lua scripts that perform certain tasks, but I
don’t know how to install them, how to use them, if I can use them with the custom version of
DT from the Debian repos or if anything else is needed… Maybe it is
explained somewhere but, up to now, I haven’t found any info on the
subject (That is , how to install them and run them). Could someone give any advise or any link to a “how to”?



In general, you don’t need something special as long as you are relying solely on the internal lua functionality. Some of the available scripts are utilizing external programs, which of course should be available on your system and installed in a way that dt/lua will find them.

(Edit: It could be that the custom version you are referring to is built without lua support, but this is unlikely.)

The more recent versions of dt have lua support (IIRC starting with 1.4), but I recommend a recent version from the 2.0 series (2.0.5 is the most recent version), since lua support improved over time and versions.

There is a repository of scripts for darktable at The installation process is described on this page as well. More details are given in the use manual, especially and there section 9.1.7. “Sharing scripts”.


Hi @Marci,

Have you seen this?

Have fun!
Claes in Lund, Sweden


On recent versions of darktable you can find out by running darktable --version.


Thanks. I’ve already installed it, though it doesn’t seem to work very well for me. I’ll keep on trying…


Hi @Marci!

Check the following:
In your /home/YourUserName/.config/darktable folder, you are supposed to have a lua folder and a luarc text file.

The luarc text file ought to contain the line
require "examples/hello_world"

The lua folder has to contain another folder, named examples
And the examples folder, i.e. /home/YourUserName/.config/darktable/lua/examples/ is to contain the text file hello_world.lua
That file contains these three lines:

local dt = require "darktable"
dt.print("hello, world")

So, whenever you start Darktable, the words hello, world ought to be shown on the monitor.

OK so far?

Have fun!
Claes in Lund, Sweden


Thank you, Claes.

This one works well, but if I install the whole bunch of scripts, for
example, appears a new tab in “preferences”, but there is no more than
the list of scripts, with no option to choose or change anything. I
haven’t tried all of them, but the gimp and hugin ones dont seem to do

But now I know how to install them and ¡that’s a start!

(Christian Kanzian) #8

You can start darktable from a terminal with

darktable -d lua

to check what goes wrong.

BTW it would be good to know which darktable version you are using. As the lua part is relatively new, most scripts require a recent darktable version.

(Tobias) #9

The gimp and hugin scripts are written for the latest git version and not the stable version.
If you use the stable dt version you need to to require “yield.lua” before “gimp.lua” in your $HOME/.config/darktable/luarc.

The “yield.lua” makes the scripts compatible with the stable dt version.

(Sören Gärup) #10

Hi all,

I’m new here and I know this is an old string, but when running:
darktable -d lua

in terminal, I get this:

LUA ERROR : /home/z/.config/darktable/lua/examples/hello_world.lua:2: Module examples/hello_world is not compatible with API 4.0.0

Does anyone have any experience with this ?


darktable 2.2.5

(Tobias) #11

Could you show me the Script?

Important is this line with the version check:

This Version should work:

(Sören Gärup) #12


change hello_world.lua to:

local dt = require "darktable"
dt.print(“hello, world”)

(Sören Gärup) #13

Thanks Tobias,

I didn’t see your answer before now, but I figured it out a week ago (see post below)

But now that I’ve got the attention from someone who knows Darktable, maybe you know the answer to this ?

I’m trying to get rid of Darktables dead thumbnails, and it seems like the solution is this:
"you may occasionally run the script from darktable’s toolset to clean-up your database. "

But what isn’t explained where to use the script ?
In terminal ?
and where is mentioned tool-set ?


(Tobias) #14

I don’t know this script, but if you look into the github log @houz, @LebedevRI and @hanatos all contributed to this script:

They should know more about it.


Yes, that’s the one. It requires an installed sqlite3 executable. And make sure to have a backup of your library.db.

(Sören Gärup) #16

Thanks a lot for the script Tobias :slight_smile:

I got the other script from but it doesn’t explain (very well) where to insert the script ?

Are scripts inserted in terminal or in some hidden feature within the Darktable GUI ?



That is a regular shell script, run from a terminal.

(Sören Gärup) #18

Thanks a lot houz :slight_smile:

I will try it out later today :slight_smile:

(Sören Gärup) #19

Thanks a lot :slight_smile:
it worked, ridded me of almost 2000 sculls :slight_smile:

Now I only wish it would generate thumbnails in the background and save a copy on the same drive as the raw files :slight_smile:

(Mica) #20

You can specify darktable’s datadir to be wherever you want it with the --datadir <data directory> switch at the command line. Or you can add that to a .desktop file.