TikZ \usegdlibrary error? graphdrawing requires LuaLaTeX

Published: 2026-05-24 Category: Tutorial / LaTeX figures Reading time: ~5 min Tags: usegdlibrary, graphdrawing, LuaLaTeX, TikZ compile errors, drawfig

---

Typical error:

! Undefined control sequence.
l.xx \usegdlibrary{layered}

Or anything involving \usetikzlibrary{graphdrawing}. Searches like “tikz usegdlibrary error” and “graphdrawing needs lualatex” point to the same fact: the graph auto-layout engine runs only on LuaTeX — default pdfLaTeX will not compile it.

📌 All TikZ compile pitfalls: 7-category TikZ failure guide

---

When do you need LuaLaTeX?

Whenever the preamble has something like:

\usetikzlibrary{graphs, graphdrawing}
\usegdlibrary{layered, force, circular}

and the tikzpicture uses automatic layout (layout=layered, layout=force, etc.), you must compile with LuaLaTeX.

---

How to switch on Overleaf

1. Top-left Menu
2. Compiler → LuaLaTeX
3. Recompile

Locally:

lualatex main.tex

---

Don't want to change compiler?

Three alternatives:

1. Remove graphdrawing — use manual \node at (x,y) or positioning's right=of (needs the positioning library).
2. Compile the figure alone with LuaLaTeX into PDF, \includegraphics in a pdfLaTeX main document.
3. Lay out in DrawFig — circular / tree / force-style layouts on canvas, then export TikZ; exported code usually does not need \usegdlibrary.

---

Common misconceptions

Myth	Reality
“Latest TeX Live is enough”	Wrong engine → same error
“XeLaTeX works too”	graphdrawing wants LuaLaTeX, not XeLaTeX
“The typo is on the \usegdlibrary line”	Root cause is the compiler, not spelling

---

DrawFig recommendation

For graph-theory papers you often do not need Lua's layout engine to get vector output:

1. Open the DrawFig editor
2. Draw directed / undirected / weighted graphs with built-in layouts
3. Export → TikZ, paste into a pdfLaTeX paper

Ideal when the school template locks pdfLaTeX and you cannot change the compiler. Pricing: Canvas editing and SVG/PNG/PDF export are free, no sign-in. TikZ export is 3 credits/use (sign-in; 30 credits/day). Credits rules.

---

Summary

• \usegdlibrary / graphdrawing → LuaLaTeX.
• Cannot switch engine → manual coordinates, include a PDF, or DrawFig layout + TikZ export.
• Related: semicolon errors, xcolor clash, main overview.