Compilers & Engines

How to Switch LaTeX Engines Without Breaking Your Document

Switching LaTeX engines mid-project can break your document if you're not careful. Font packages, encoding declarations, and some commands are engine-specific. This tutorial provides a step-by-step migration guide that handles the most common compatibility issues when moving between pdfLaTeX, XeLaTeX, and LuaLaTeX. Bibby AI can perform this migration automatically — just tell it which engine you want, and it updates your preamble while preserving your document structure.

Migrating from pdfLaTeX to XeLaTeX/LuaLaTeX

The most common migration. Follow these steps to update your preamble:

% === BEFORE (pdfLaTeX preamble) ===
\documentclass{article}
\usepackage[utf8]{inputenc}    % Remove
\usepackage[T1]{fontenc}       % Remove
\usepackage{mathpazo}          % Replace
\usepackage{microtype}         % Modify
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}

% === AFTER (XeLaTeX/LuaLaTeX preamble) ===
\documentclass{article}
% inputenc and fontenc are NOT needed
\usepackage{fontspec}          % New
\setmainfont{TeX Gyre Pagella} % Replaces mathpazo
\usepackage[protrusion=true]{microtype} % Limited
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}

% For LuaLaTeX specifically, you can also use:
\usepackage{unicode-math}
\setmathfont{TeX Gyre Pagella Math}

Migrating from XeLaTeX/LuaLaTeX to pdfLaTeX

Going back to pdfLaTeX requires replacing fontspec with traditional font packages:

% === BEFORE (XeLaTeX preamble) ===
\documentclass{article}
\usepackage{fontspec}
\setmainfont{Times New Roman}
\setsansfont{Arial}
\setmonofont{Courier New}
\usepackage{unicode-math}
\setmathfont{XITS Math}

% === AFTER (pdfLaTeX preamble) ===
\documentclass{article}
\usepackage[utf8]{inputenc}     % Required for UTF-8
\usepackage[T1]{fontenc}        % Better font encoding
\usepackage{newtxtext,newtxmath} % Times-like fonts
% or for specific font families:
% \usepackage{mathptmx}    % Times
% \usepackage{helvet}      % Helvetica (sans)
% \usepackage{courier}     % Courier (mono)

% ALSO: Replace Unicode characters with commands:
% XeLaTeX: café, naïve, €
% pdfLaTeX: caf\'e, na\"ive, \texteuro{}

Writing Engine-Agnostic Documents with ifxetex/ifluatex

Create documents that compile with ANY engine by using conditional compilation:

\documentclass{article}
\usepackage{iftex}  % Modern package for engine detection

\ifPDFTeX
  % pdfLaTeX-specific setup
  \usepackage[utf8]{inputenc}
  \usepackage[T1]{fontenc}
  \usepackage{mathpazo}
\else
  % XeLaTeX or LuaLaTeX setup
  \usepackage{fontspec}
  \setmainfont{TeX Gyre Pagella}
  \ifLuaTeX
    % LuaLaTeX-only features
    \usepackage{unicode-math}
    \setmathfont{TeX Gyre Pagella Math}
  \fi
\fi

% Engine-agnostic packages
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}

\begin{document}
\section{Introduction}
This document compiles with any engine!

\begin{equation}
  E = mc^2
\end{equation}
\end{document}

% Now compile with any command:
% pdflatex main.tex
% xelatex main.tex
% lualatex main.tex

💡 Tips

•The iftex package is the modern, clean way to write engine-agnostic documents — use it instead of the older ifxetex and ifluatex packages.
•Bibby AI can migrate your document between engines automatically — just change the engine setting and it updates your preamble.
•Always test-compile after switching engines, even if you think you've updated everything — edge cases are common.
•Keep a backup of your working preamble before switching engines, so you can revert quickly if things break.

Try This in Bibby AI

Write LaTeX faster with AI auto-complete and instant compilation.

Start Writing Free