How do I debug BibTeX code? I would like to know how to:

  • step through execution,
  • step into and out of function calls,
  • set breakpoints,
  • visualize the stack,
  • watch the values of various variables,

et cetera. Are there any debugging options for BibTeX, perhaps like the unravel package (available on CTAN and on GitHub) for LaTeX?
     The reason I'm asking such a question is because I have been going through texdoc tamethebeast (Nicolas Markey's Tame the BeaST: The B to X of BibTeX) for a little while now and would like to have a better understanding of what's going on in some of the examples it presents in Chapter 4, particularly some of the later ones (starting around section 20 in said chapter) since they appear to get quite complex. There has to be a better way to go about inspecting how BibTeX code of the like executes and manipulates the stack than writing them out step by step in a sort of annotated textual control-flow graph in a raw text file or — I shudder to think! — getting out pencil and paper! (This last option would be less of a problem if I had room next to the computer from which I'm typing this on the desk it's standing on, but, still, it seems…needlessly archaic, shall I say…?)

  • 1
    I guess that most people who know BibTeX are also reasonable TeX programmers, so the approach of 'Edit in $pop, check the values, track them on a piece of paper' is seen as pretty standard ...
    – Joseph Wright
    Mar 20, 2018 at 21:52
  • 4
    BibTeX is an independent program that's over 40% the size of TeX itself. Like TeX it is written in WEB, which is Pascal plus support for TeX documentation plus some preprocessor-like features that must have seemed a good idea at the time. Like TeX it is, in most distributions, converted to unreadable C code using web2c (instead of to unreadable Pascal code using tangle). So I guess the answer is: like TeX, BibTeX can be debugged (poorly) by building it from scratch and running in a debugger. Probably would be easier to just use Biber/BibLaTeX. Mar 20, 2018 at 22:33
  • 1
    You could build your own binary of BibTeX with the debug, stats, and trace flags enabled, see github.com/texlive/texlive-source/blob/… Mar 20, 2018 at 22:53
  • 1
    @HenriMenke I think the suggestion of building with trace turned on may be posted as an answer, because the question is really “how can I best debug BibTeX / see what's going on”, rather than asking for a software recommendation (when we all know that no such software exists). Mar 20, 2018 at 23:03
  • 1
    @ShreevatsaR Therefore the question would have to be rephrased because currently it literally asks “Is there a debugger for BibTeX?” and “Such a tool should allow [...]” rather than “How to debug BibTeX?”. Mar 20, 2018 at 23:07

1 Answer 1


I think your best bet here is to compile your own bibtex executable where you enable the trace flag.

From the BibTeX source code (bibtex.web):

Some of the code below is intended to be used only when diagnosing the
strange behavior that sometimes occurs when \BibTeX\ is being
installed or when system wizards are fooling around with \BibTeX\
without quite knowing what they are doing. Such code will not normally
be compiled; it is delimited by the codewords
`$|debug|\ldots|gubed|$', with apologies to people who wish to
preserve the purity of English. Similarly, there is some conditional
code delimited by `$|stat|\ldots|tats|$' that is intended only for use
when statistics are to be kept about \BibTeX's memory/cpu usage,
and there is conditional code delimited by `$|trace|\ldots|ecart|$'
that is intended to be a trace facility for use mainly when debugging
\.{.bst} files.

@d debug == @{          { remove the `|@{|' when debugging }
@d gubed == @t@>@}      { remove the `|@}|' when debugging }
@f debug == begin
@f gubed == end
@d stat == @{           { remove the `|@{|' when keeping statistics }
@d tats == @t@>@}       { remove the `|@}|' when keeping statistics }
@f stat == begin
@f tats == end
@d trace == @{          { remove the `|@{|' when in |trace| mode }
@d ecart == @t@>@}      { remove the `|@}|' when in |trace| mode }
@f trace == begin
@f ecart == end

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.