Writing LaTeX macros has always been difficult, and it seems like writing a major package can only be accomplished by a Real Programmer.

Fortunately, LuaTeX is on its way, and writing Lua macros is arguably more human-friendly than programming in TeX. Still, it could get even friendlier if there was a way to couple LuaTeX with a remote debugger.

Therefore I ask: Is there a way to remotely debug LuaLaTeX macros?

This question is essentially a rewording of the post Debugging Lua in LuaLatex with LDT. The post was closed since it didn't really contain a question. An almost-complete solution was proposed in the post, but there were some issues, and I would like to know if these issues can be resolved.

  • Could you explain 'remote' debugging for those of us without a formal programming background?
    – Joseph Wright
    Feb 23, 2016 at 19:29
  • Basically, I want to write my macro in a file macro.lua, using a text editor with debugging capabilities (such as Emacs or Eclipse). When I compile the .tex document, I want LuaTeX to pass the control over to Emacs/Eclipse, where I can step through the macro line by line, examining (and possibly alter) the contents of macro variables as the program progresses.
    – akvilas
    Feb 23, 2016 at 19:49
  • 1
    @JosephWright debuggers let you single step through compiled languages like C or Fortran so could in principle do the same in lua. Feb 23, 2016 at 20:17
  • 2
    Basically can you access something like this from luatex: lua-users.org/wiki/DebuggingLuaCode Feb 23, 2016 at 20:20
  • 1
    I usually do printf debugging in combination with viz-nodelist (when appropriate, see for an example output tex.stackexchange.com/a/107398/243). My printf debug functions are here: github.com/speedata/publisher/blob/develop/src/lua/common/…, especially w() and printtable().
    – topskip
    Feb 23, 2016 at 20:46

2 Answers 2


Nowadays you can get GUI debugging of Lua code right in the middle of LuaTeX processing of your document. With breakpoints, watch variables, stepping through the code, call stack, and even showing tooltips with variable content on mouse hover.

My environment for working with TeX is VS Code + LaTeX Workshop + LTeX. It's quite convenient: I can write and debug a C++ program, and in the same window write a paper that describes it. LaTeX Workshop has so many features that anything like TeXstudio feels unnecessary.

You also can edit your TeX document and debug its Lua in the same environment of VS Code. To support and debug Lua inside your document, you need two extensions: Lua and Local Lua Debugger.

In order to debug, insert the following in your preamble:


Then create the following launch configuration:

    "version": "0.2.0",
    "configurations": [
            "name": "Debug Custom Lua Environment",
            "type": "lua-local",
            "request": "launch",
            "stopOnEntry": false,
            "program": {
                "command": "lualatex"
            "args": ["mwe.tex"]

That's it. You are ready to debug, just press F5. The only drawback so far: it cannot place a breakpoint inside a .tex document, it has to be a Lua file.

Here is a screenshot of a debug session:

enter image description here


One simple, lightweight alternative is the command-line interface debugger debugger.lua by Scott Lembcke. This is not a remote debugging solution, but it is very easy to set up. On the downside, there is no GUI, so everything is done through the terminal. But it's way better than issuing print commands, which is probably the approach used by most LuaLaTeX package writers to date.

To get started:

  1. Download debugger.lua and place it in your project folder.
  2. Place the command local dbg = require("debugger") at the start of the .lua file you want to debug.
  3. Place the command dbg() at places in your code where you want code execution to break.
  4. Use terminal commands to inspect variables, execute custom code and more. Issue the command h to get a simple summary of available commands.
  • If someone can give me a simple-to-set-up GUI debugging solution, I'll accept that anwer instead of my own...
    – akvilas
    Feb 24, 2016 at 7:45

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .