Debugging Adobe Lightroom plugins with ZeroBrane Studio

(This post is by Christopher Reimold, who tested and documented the details of Adobe Lightroom plugin debugging.)

Adobe Photoshop Lightroom is a photo management and editing program that offers the ability to extend its functionality through plugins written in Lua. Debugging Lightroom plugin scripts has often been a somewhat cumbersome process, in which one had to resort to printing of variables to the console in order to understand what's going on in your plugin. However, there is now the possibility to use full in-editor interactive debugging which we will briefly demonstrate in this article.

Minimally useful demo Lightroom plugin script

We use the following short script to demonstrate developing and debugging of a Lightroom (LR) plugin in ZeroBrane Studio Lua IDE. The plugin shows the exposure value to the user. To create a plugin for LR, you have to create at least two files and one directory:

(1) The Info.lua file, which is a manifest that provides information about your plugin to LR. Its name is always Info.lua.

(2) Your actual plugin, which is called ShowExposureValue.lua in this example. It is referenced from your Info.lua file, as shown in the highlighted fragment above.

Put these two files into a directory called ExposureValue.lrplugin; the directory can reside anywhere on your hard disk. The .lrplugin extension will make LR recognize this directory as a plugin. On OSX, .lrplugin directories are recognized and treated as a package (single file). This can sometimes be problematic during development, and you can thus use .lrdevplugin as an extension on OSX if you want to avoid this.

If you want to learn more about developing an LR plugin, please have a look at the Lightroom SDK, in particular the programmer's guide and the API reference.

Installing and running the plugin

To make the plugin known to Lightroom, open File | Plugin-Manager. In the dialog, select Add and add your .lrplugin directory. The plugin should now show as Display Exposure Value: Installed and running in the left column. For development purposes, do check the Reload plug-in on each export option; this way you can be sure that the latest version of your script will be run. Close the dialog.

If all has gone according to plan, you should now be able to find the plugin in the menu File | Plug-in Extras | Show Exposure Value. Start the plugin by selecting this menu item, and a dialog such as the following should appear:

Preparing your script for debugging

In order to use ZeroBrane Studio (ZBS) as an interactive debugger, you now need to make some (minor) modifications to your script and environment so that the plugin and ZBS can communicate:

  • Copy the files Info.lua, LrMobdebug.lua, and mobdebug.lua into the following directory:
    • Mac: ~/Library/Application\ Support/Adobe/Lightroom/Modules/mobdebug.lrmodule
    • Windows: C:\Program Files\Adobe\Adobe Photoshop Lightroom 5.3\Modules\mobdebug.lrmodule

This module contains the LrMobdebug namespace which will enable LR to communicate with ZBS. This module is not a plugin and don't need to be installed/added as a plugin to LR.

  • Have a look at the file mobdebug.lrmodule you just installed. The version field in the Info.lua manifest there has to match the major.minor version number of your Lightroom installation, or the debugging will not work (as the module will not be loaded by Lightroom). So, if you're using LR 5.3, make sure you set major version in that file to 5 and minor to 3.

Changes to your script

Now, add the following line somewhere near the beginning of your plugin: local LrMobdebug = import 'LrMobdebug'. Note: Import will throw an error if this module is not present, so if you are deploying your plugin on a customer's system, you'd need to comment out or remove all calls which refer to LrMobdebug.

Add LrMobdebug.start() call at the point where you would like the debugging to start. This will connect your script, running within the Lightroom environment, to the ZeroBrane debugger server and thus enable debugging from that execution point. (Note: LrMobdebug.start() will usually act like a breakpoint, i.e. execution will stop immediately after it; if you do not want this behavior, you can use the debugger.runonstart = true configuration setting in ZeroBrane Studio in order to avoid breaking at that point.)

Add LrMobdebug.on() after the beginning of any coroutine, i.e. LrTasks.startAsyncTask(function() LrMobdebug.on() ...).

Interactive debugging with ZBS

Now, we're ready to start stepping interactively through our application.

  • Open ZeroBrane Studio, go to Project | Start Debugger Server and start the debugger server (if this menu item is checked or disabled, the server is already started). When your script hits the LrMobdebug.start() command, this command will connect your script to the ZeroBrane debugger server. Therefore, the debugger server must be started before executing your plugin.
  • Make sure your plugin script is open in ZBS.
  • Set the project directory to the directory of your plugin by going to Project | Project Directory | Choose... or using Project | Project Directory | Set From Current File.
  • Set a breakpoint in your script by clicking in the column directly to the right of the line numbers. A red circle signifies that you have successfully set a breakpoint.
  • Start your plugin in Lightroom, as described above. You should see a green arrow pointing to the next statement after the start() call in ZeroBrane Studio and should be able to step through the code.

Working with the debugger

  • Step through your program with the Step Into command, directly next to the Pause button. Step Into steps into functions, whereas Step Over steps over functions, as usual.
  • If you are interested in a variable, right-click it and Add Watch Expression.
  • The Stack Window shows the contents of the call stack.
  • You can rearrange windows to have the stack and watch window always in view, as shown in the screenshot below.
  • Select Project | Continue to continue execution of your script. It will stop at the next breakpoint, or run until termination if there is no next breakpoint.
  • If you want to interrupt your debugging activities for a while, you can simply stop the debugging or switch off the debugger server by unchecking Project | Start Debugger Server option (in ZBS v0.51+).

Many thanks to Dan Tull who provided details on how the debugger can be called from Adobe Lightroom to get access to the required functionality.

You should get a copy of my slick ZeroBrane Studio IDE and follow me on twitter here.


Having problems getting this working on OSX

When you say "Make sure your plugin script is open in ZBS" - is this the version of the script in the .lrdevplugin package? In which case, how do you get that open in ZBS, and set that as the Project directory?

Yes, this is the script in .lrdevplugin folder. You need to open ZBS, then open the script in it (Cmd-O) and then set the project directory (Project | Project Directory | Set From Current File). Paul.


i use LR CC 2015 in Windows7. I copy your 3 files in C:\Program Files\Adobe\Adobe Photoshop Lightroom cc 2015\Modules\mobdebug.lrmodule

I have insert your code in my script... But when a user my plugins in LR, this message appear: "Could not find namespace: LrMobdebug"

please help me.

@seb, you may need to make sure that the version number number in info.lua file ("VERSION = { major=5, minor=3, revision=0, build=200000 }") matches the version number in your Lightroom installation. I have a note about this at the bottom of the "Preparing your script for debugging" section.

Leave a comment

what will you say?


I am Paul Kulchenko.
I live in Kirkland, WA with my wife and three kids.
I do consulting as a software developer.
I study robotics and artificial intelligence.
I write books and open-source software.
I teach introductory computer science.
I develop a slick Lua IDE and debugger.