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.


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.

Hi, how can i unload the module mobdebug.lrmodule from Lightroom. Every time i do a change in the module i get an error message from lightroom.

Not sure if this is still alive. Anyway, I'll give it a try. Precisely following the instructions (at least I think I did), I cannot get this to work. Namespace LrMobdebug cannot be found is all I get. I am using LR 2015.6, and have inserted

VERSION = { major=6, minor=6, revision=0, build=1078672 }

into info.lua (I tried even both instances of this file in mobdebug.lrmodule and ExposureValue.lrplugin as well.

What's wrong here??

@Drogg, not sure about unloading, but you can rename Info.lua, which will prevent the plugin from loading. Also, you should not need to make changes in the debugger; what kind of error message are you getting?

@karsten, this has been tested on the previous version of LR, so something might have changed with the upgrade to v6. I sent you details over email, so we may continue there as it's a more reliable channel. Paul.

I cannot get this to work. Namespace LrMobdebug cannot be found is all I get.

I am using LR 6.

VERSION = { major=6, minor=0 revision=0, build=1014445 }

I have copied the 3 files to the following folder: C:\Program Files\Adobe\Adobe Lightroom\Modules\mobdebug.lrmodule

Can you tell me what I am doing wrong here ?

I also cannot get this to work. I've got this message when I try to run ShowExposureValue plugin:

An internal error has occurred.

module 'mobdebug' not found: no field package.preload['mobdebug'] no file './' no file '/usr/local/lib/lua/5.1/' no file '/usr/local/lib/lua/5.1/'

If I change version in info.lua from 6.7 to any other value the message is: Could not find namespace: LrMobdebug

So, I think, the version is OK, LR loads or tries to load the module, but there is a problem during execution of the ShowExposureValue script.

Lightroom 6.7 macOS Sierra 10.12.1

It did work for me very well with LR 6.6 (I did use LR CC 2015.6), with LR 6.7 (LR CC 2015.7 [ 1090788 ], Windows 10 Pro 1607 64 bit) I always get "Could not find namespace: LrMobdebug".

I tried all combinations of major (6, 2015), minor (7) and build (200000, 1090788).

Please help!

Thank you in advance - Ed

Debug is working again!

My settings in Info.lua for LrMobdebug: VERSION = { major=6, minor=7, revision=0, build=10 }

These values are taken from the details tab of the properties window for lightroom.exe (

There must have been some changes in module-handling between LR 6.6 and LR 6.7.

Kind regards - ED

Hi Ed, glad you got it working. Thank you for sharing your solution!

I have MacBook. I try to copy related files into ~/Library/Application\ Support/Adobe/Lightroom/Modules/mobdebug.lrmodule folder but I don't have 'Modules' into Lightroom folder.

I tried to create that folder by manually but my debugging didn't work.

Do yo have any idea?

Thanks in advance.

Could not get it working with LR 7.4

Probably many people would appreciate including myself to have an update on the article.

I have to change my statement. I could get it running with exposure plugin. Thank you

Get internal error on LightRoom Classic 9.4. Put the directory - mobdebug.lrmodule in directory: C:\Program Files\Adobe\Adobe Lightroom Classic\Modules

Changed Info.lua: VERSION = { major=9, minor=4, revision=0, build=202005281810-476e492 }

Get message: Could not find namespace: LrMobdebug

Have I put the mobdebug.lrmodule in the WRONG directory or ???

Leave a comment

what will you say?