repository·master·Indexed 42 days ago
https://github.com/darktable-org/lua-scriptsA collection of official, community-contributed, and example Lua scripts for darktable. This repository provides extended functionality, automation, and tools through the darktable Lua scripting interface, including scripts for metadata management, HDR blending, facial recognition, and API demonstration.
luarc file in a text editor and insert -- at the beginning of the line containing the script you wish to disable. This uses standard Lua comment syntax.The recommended installation method is to clone the repository using git into your darktable configuration directory. This ensures dependencies are met and allows for easy updates. Note that AppImage packages do not support Lua scripts as they lack an internal Lua interpreter.
Select the command corresponding to your installation method:
~/snap/darktable/current~/.var/app/org.darktable.Darktable/config/darktable~/.config/darktable/%LOCALAPPDATA%\darktable (ensure darktable has been run at least once to create this directory).# Example for Linux/MacOS
cd ~/.config/darktable/
git clone https://github.com/darktable-org/lua-scripts.git lua
# Example for Windows (Command Prompt)
cd %LOCALAPPDATA%\darktable
git clone https://github.com/darktable-org/lua-scripts.git luaTo update your installed scripts, navigate to the lua directory within your darktable configuration folder and perform a git pull.
# Example for Linux/MacOS
cd ~/.config/darktable/lua/
git pullDarktable loads scripts by reading a plain text file named luarc located in your darktable configuration directory. Each line in the file must follow the format require "<directory>/<name>".
Recommended Approach: Enable the script_manager module, which provides a UI for managing scripts.
Manual Approach: You can create or append to the luarc file using command-line tools like echo.
Configuration Locations:
~/.config/darktable/luarc%LOCALAPPDATA%\darktable\luarc~/snap/darktable/current/luarc~/.var/app/org.darktable.Darktable/config/darktable/luarc# Enable script manager on Linux/MacOS
echo 'require "tools/script_manager"' > ~/.config/darktable/luarc
# Add a specific script (e.g., hugin) on Windows
echo require "contrib/hugin" >> %LOCALAPPDATA%\darktable\luarcIf scripts are not behaving as expected, you can run darktable with Lua debugging enabled to see detailed information in the terminal or a log file.
Commands by Platform:
snap run darktable -d luadarktable -d lua/Applications/darktable.app/Contents/MacOS/darktable -d lua"C:\Program Files\darktable\bin\darktable" -d lua > log.txt (run from a command prompt)# Linux debugging
darktable -d luaThe project provides several documentation resources:
Tool scripts perform functions related to the repository, such as generating documentation. They are located in the tools/ directory.
| Name | Standalone | OS | Purpose |
|---|---|---|---|
executable_manager | Yes | LMW | Manage the external executables used by the lua scripts |
gen_i18n_mo | No | LMW | Generate compiled translation files (.mo) from source files (.po) |
get_lib_manpages | No | LM | Retrieve the library documentation and output it in man page and PDF format |
get_libdoc | No | LMW | Retrieve the library documentation and output it as text |
script_manager | No | LMW | Manage (install, update, enable, disable) the lua scripts |
Contributed scripts are maintained by community members and are located in the contrib/ directory. They are categorized by whether they are Standalone and their supported Operating Systems (L: Linux, M: MacOS, W: Windows).
| Name | Standalone | OS | Purpose |
|---|---|---|---|
AutoGrouper | Yes | LMW | Group images together by time |
autostyle | Yes | LMW | Automatically apply styles on import |
auto_tag_modified | Yes | LMW | Automatically tag images which have been manually modified in the darkroom |
change_group_leader | Yes | LMW | Change which image leads group |
clear_GPS | Yes | LMW | Reset GPS information for selected images |
CollectHelper | Yes | LMW | Add buttons to selected images module to manipulate the collection |
color_profile_manager | Yes | LMW | Manage darktable input and output color profiles |
copy_attach_detach_tags | Yes | LMW | Copy and paste tags from/to images |
cr2hdr | Yes | L | Process image created with Magic Lantern Dual ISO |
cycle_group_leader | Yes | LMW | cycle through images of a group making each the group leader in turn |
dbmaint | Yes | LMW | find and remove database entries for missing film rolls and images |
enfuseAdvanced | No | LMW | Merge multiple images into Dynamic Range Increase (DRI) or Depth From Focus (DFF) images |
exportLUT | Yes | LMW | Create a LUT from a style and export it |
ext_editor | No | LW | Export pictures to collection and edit them with up to nine user-defined external editors |
face_recognition | No | LM | Identify and tag images using facial recognition |
fujifilm_dynamic_range | No | LMW | Correct fujifilm exposure based on exposure bias camera setting |
fujifilm_ratings | No | LM | Support importing Fujifilm ratings |
geoJSON_export | No | L | Create a geo JSON script with thumbnails for use in ... |
geoToolbox | No | LMW | A toolbox of geo functions |
gimp | No | LMW | Open an image in GIMP for editing and return the result |
gpx_export | No | LMW | Export a GPX track file from selected images GPS data |
harmonic_armature | Yes | LMW | provide a harmonic armature guide |
hif_group_leader | Yes | LMW | change the group leader in a raw+heif image pair to the heif image |
HDRMerge | No | LMW | Combine the selected images into an HDR DNG and return the result |
hugin | No | LMW | Combine selected images into a panorama and return the result |
image_stack | No | LMW | Combine a stack of images to remove noise or transient objects |
image_time | Yes | LMW | Adjust the EXIF image time |
jpg_group_leader | Yes | LMW | change the group leader for a raw+jpg pair to the jpg image |
kml_export | No | L | Export photos with a KML file for usage in Google Earth |
LabelsToTags | Yes | LMW | Apply tags based on color labels and ratings |
OpenInExplorer | No | LMW | Open the selected images in the system file manager |
passport_guide | Yes | LMW | Add passport cropping guide to darkroom crop tool |
passport_guide_germany | Yes | LMW | Add passport cropping guide for German passports to darkroom crop tool |
pdf_slideshow | No | LM | Export images to a PDF slideshow |
photils | No | LM | Automatic tag suggestions for your images |
quicktag | Yes | LMW | Create shortcuts for quickly applying tags |
rate_group | Yes | LMW | Apply or remove a star rating from grouped images |
rename_images | Yes | LMW | Rename single or multiple images |
rename-tags | Yes | LMW | Change a tag name |
RL_out_sharp | No | LW | Output sharpening using GMic (Richardson-Lucy algorithm) |
select_non_existing | Yes | LMW | Enable selection of non-existing images in the the currently worked on images |
select_untagged | Yes | LMW | Enable selection of untagged images |
slideshowMusic | No | L | Play music during a slideshow |
transfer_hierarchy | Yes | LMW | Image move/copy preserving directory hierarchy |
video_ffmpeg | No | LMW | Export video from darktable |
website_gallery_export | No | LMW | Export a website gallery for selected images |
Example scripts are located in the examples/ directory. They are intended for demonstration purposes to show how to use specific portions of the darktable Lua API. They are categorized by whether they are Standalone and their supported Operating Systems (L: Linux, M: MacOS, W: Windows).
| Name | Standalone | OS | Purpose |
|---|---|---|---|
api_version | Yes | LMW | Print the current API version |
darkroom_demo | Yes | LMW | Demonstrate changing images in darkroom |
gettextExample | Yes | LM | How to use translation |
gui_actions | Yes | LMW | demonstrate controlling the GUI using darktable.gui.action calls |
hello_world | Yes | LMW | Prints hello world when darktable starts |
lighttable_demo | Yes | LMW | Demonstrate controlling lighttable mode, zoom, sorting and filtering |
moduleExample | Yes | LMW | How to create a lighttable module |
multi_os | No | LMW | How to create a cross platform script that calls an external executable |
panels_demo | Yes | LMW | Demonstrate hiding and showing darktable panels |
preferenceExamples | Yes | LMW | How to use preferences in a script |
printExamples | Yes | LMW | How to use various print functions from a script |
running_os | Yes | LMW | Print out the running operating system |
x-touch | Yes | LMW | demonstrate how to use an x-touch mini MIDI controller to control the darktable GUI |
Official scripts are maintained by darktable developers and are located in the official/ directory. They are categorized by whether they are Standalone (can be run by themselves) and their supported Operating Systems (L: Linux, M: MacOS, W: Windows).
| Name | Standalone | OS | Purpose |
|---|---|---|---|
check_for_updates | Yes | LMW | Check for updates to darktable |
copy_paste_metadata | Yes | LMW | Copy and paste metadata, tags, ratings, and color labels between images |
delete_long_tags | Yes | LMW | Delete all tags longer than a specified length |
delete_unused_tags | Yes | LMW | Delete tags that have no associated images |
enfuse | No | L | Exposure blend several images (HDR) |
generate_image_txt | No | L | Generate txt sidecar files to be overlaid on zoomed images |
image_path_in_ui | Yes | LMW | Plugin to display selected image path |
import_filter_manager | Yes | LMW | Manager for import filters |
import_filters | No | LMW | Two import filters for use with import_filter_manager |
save_selection | Yes | LMW | Provide save and restore from multiple selection buffers |
selection_to_pdf | No | L | Generate a PDF file from the selected images |