Skip to content
checkcites is a Lua script written for the sole purpose of detecting undefined/unused references from LaTeX auxiliary or bibliography files.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Updated documentation, ready for upload. Aug 25, 2017
README.markdown Added link to issue. Dec 18, 2012
checkcites.lua Added comments. Aug 24, 2017



Current stable version: 1.0i from December 18, 2012

The script

checkcites.lua is a humble Lua script written for the sole purpose of detecting unused or undefined references from LaTeX auxiliary (.aux) or bibliography (.bib) files.

The idea came from this answer of mine in the community. My good friend Enrico Gregorio encouraged me and gave me great ideas to write this script, so we came up with checkcites.lua!

How it works

First of all, we analyze the .aux file and extract both citations and bibliography. Let's call the citations set A.

Now, we extract all entries from the bibliography files we found referenced in the previous step. Let's call the bibliography entries set B.

Now we have both sets, let's do the math! If we want to get all undefined references in our .tex file, we simply go with:

Undefined references

For unused references in our .bib file(s), we go with:

Unused references


The script is pretty simple to use. The only requirement is a recent TeX distribution, such as TeX Live. Then run checkcites.lua:

$ texlua checkcites.lua

It will print the script usage. The only required argument is the .aux file which is generated when you compile your .tex file. If your main document is named foo.tex, you will have a foo.aux file too. To run the script on that file, go with

$ texlua checkcites.lua foo.aux

checkcites.lua allows an additional argument that will tell it how to behave. For example

$ texlua checkcites.lua --unused foo.aux

will make the script only look for unused references in your .bib file. The argument order doesn't matter, you can also run

$ texlua checkcites.lua foo.aux --unused

and get the same behaviour. Similarly, you can use

$ texlua checkcites.lua --undefined foo.aux

to make the script only look for undefined references in your .tex file. If you want checkcites.lua to look for both unused and undefined references, go with

$ texlua checkcites.lua --all foo.aux

If no special argument is provided, --all is set as default.


This script is licensed under the LaTeX Project Public License. If you want to support LaTeX development by a donation, the best way to do this is donating to the TeX Users Group.

The authors

You can reach us through the following links:

You can also find us in the TeX, LaTeX and Friends chatroom of the community.



Fixed issue #1: bibliography entries with leading whitespace before the cite key were causing problems because the whitespace was being extracted alongside the key. The patch was kindly provided by Constantine Lignos.


If \citation{*} is found, checkcites will issue a message telling that \nocite{*} is in the .tex document, but the script will do the check nonetheless.


First public release. Yay!

You can’t perform that action at this time.