LaTeX engines & packages
Choose Tectonic or a latexmk compiler, use an existing TeX distribution, or install Oleafly's managed TinyTeX.
Oleafly ships Tectonic and can also compile through latexmk. The project compiler menu controls day-to-day builds. Settings → Engines shows the TeX distributions and packages available on your machine.
Tectonic: the everyday engine
Section titled “Tectonic: the everyday engine”Tectonic is the default compile engine until you pick another under Default compile engine in Settings → Engines → LaTeX. It needs no separate installation, fetches packages as needed, and caches them for offline use. It is a good fit for most projects and remains available even when no system TeX distribution is installed. See Set a default for new projects.
For tagged PDFs, use the LuaLaTeX workflow. Tags describe document structure for assistive technology. Inspect the result with Preflight after compiling.
Fonts on the built-in engine
Section titled “Fonts on the built-in engine”Tectonic is based on XeTeX, which reads font files directly. Oleafly adjusts a few things so documents written for pdfLaTeX keep their fonts and text:
-
Times, Helvetica, Courier, Palatino, Bookman, New Century Schoolbook, and Avant Garde use their TeX Gyre versions instead of falling back to Latin Modern.
-
\usepackage[T1]{fontenc}breaks typed accents and symbols on this engine, so Oleafly keeps the document on Unicode text. If a font the document uses only exists in T1, the document stays on T1 and the compile warns that characters such as ß, §, «, curly quotes, and € can print wrong or vanish. The warning gives a version of the line that loads T1 only under pdfLaTeX:\usepackage{iftex}\ifPDFTeX\usepackage[T1]{fontenc}\fi -
A document that sets
\pdfoutput=1, as arXiv asks, compiles as it is. -
A
ctexdocument that sets nofontsetgets the Fandol fonts, so it looks the same on every computer. Addfontset=macto the class options to use the Mac’s own fonts. -
Fonts that come with the built-in engine are found by file name.
\setmainfont{UnBatang}fails, and the error tells you to writeUnBatang.ttfinstead.
Offline mode skips the font and encoding adjustments, so an offline build of such a document can look different from an online one.
latexmk and system TeX
Section titled “latexmk and system TeX”Choose pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, or pLaTeX from a project’s compiler menu when the project depends on a traditional TeX Live or MiKTeX workflow. Oleafly runs those compilers through latexmk. Auto reads the main file and picks one: a % !TeX program = xelatex line at the top wins, then Japanese classes, then packages that need XeLaTeX or LuaLaTeX, such as fontspec, ctex, xeCJK, or luatexko. If the main file doesn’t settle it, Auto also checks a latexmkrc in the project and the files the preamble loads. Everything else uses pdfLaTeX. If a package needs a different compiler than the one Auto picked, the compile offers to switch, for example with Use XeLaTeX.
There are two ways to provide that toolchain:
- Use an existing installation. Oleafly detects MacTeX, TeX Live, MiKTeX, and TinyTeX on your system. It looks on the same
PATHyour terminal uses and, on Windows, in the system and userPathsettings too, so a TeX you installed by hand is found even when the app was opened from the Dock or Start menu. A system installation takes priority over Oleafly’s managed copy only when its binary directory containslatexmk, pdfLaTeX, XeLaTeX, LuaLaTeX,kpsewhich, and Biber. A partial installation cannot silently outrank a working managed TinyTeX. - Install managed TinyTeX. The download is about 250 MB and needs no administrator access. See Install and update TinyTeX.
Manage TeX distributions in Settings → Engines → LaTeX lists every distribution Oleafly found. In use marks the one latexmk compiles with, and a latexmk badge marks each one that can compile. Choose Use for compiles on another row to switch to it. The row you chose then shows Automatic, which lets Oleafly pick again: a complete system TeX first, then TinyTeX.
If TeX is installed in a folder Oleafly doesn’t look in, click Choose a TeX folder and pick the folder with latexmk in it, or the TeX Live year folder above it, such as texlive/2026. Oleafly finds latexmk inside and compiles with that installation, which the list marks In use. Automatic undoes the choice. If the folder has no latexmk, the message says which folder to pick instead.
latexmk is not a filesystem sandbox. Even with shell commands blocked, TeX can read files available to your account. Oleafly also disables project, user, and system .latexmkrc files because they are executable Perl. Use system TeX only for projects you trust. An imported project uses system TeX only when you choose it, either as the default compile engine or from the project’s compiler menu. A folder you open in place stays on Tectonic until you trust it.
When no TeX is installed
Section titled “When no TeX is installed”Picking pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, pLaTeX, or Auto on a computer without a working TeX distribution opens a dialog titled This compiler needs a working TeX distribution. It shows three options, in this order:
- Download TinyTeX, marked Recommended. Download and use TinyTeX installs TinyTeX and compiles the project with it.
- Use my system LaTeX (latexmk), which says that no TeX distribution was found, or why the one on this computer can’t compile. It has no button.
- Keep using Tectonic. Switch back to Tectonic returns the project to the built-in engine.
If you compile first, the preview offers the same way out: Download and use TinyTeX, Use Tectonic, and Open engine settings. A compile you start while TinyTeX is still downloading waits and starts on its own when the install finishes.
The same offer appears when a TeX distribution is there but has no latexmk. When the distribution lacks latexmk, the chosen compiler, or Biber, the message also names what to install when Oleafly knows the distribution, such as sudo tlmgr install latexmk on MacTeX or sudo apt install latexmk on Ubuntu.
In a shared project, the button reads Use Tectonic for everyone, because the compiler is saved in the project and changes for every collaborator. Installing TinyTeX only changes your computer.
Install and update TinyTeX
Section titled “Install and update TinyTeX”Open Settings → Engines → LaTeX and choose Download TinyTeX (~250 MB) under Manage TeX distributions, or use the offer in the compile dialog. TinyTeX is a compact TeX Live that needs no administrator rights. Journal templates can add packages later, up to about 1 GB in total, and Oleafly checks for about 2 GB of free disk space before it starts. TinyTeX installs under ~/.oleafly/tinytex.
- Cancel stops the download and keeps what has arrived. The button then reads Resume download with the amount already done. Quitting Oleafly during the install pauses it the same way, and it continues the next time you open the app.
- The download comes from Oleafly’s mirror first, then from GitHub. If a source fails, or stops sending data for a minute, Oleafly moves to the next one and continues where it stopped. Settings → Downloads → Sources changes where downloads come from. See Sources tab.
- When the managed TinyTeX is older than the release this version of Oleafly expects, its row shows Update. Remove deletes it.
If another distribution is already In use, installing TinyTeX doesn’t switch to it. Choose Use for compiles on the TinyTeX row when you want it to compile.
On Linux, TinyTeX runs on the system Perl. Oleafly checks for Perl before it downloads anything. If Perl or one of its standard modules is missing, the message gives the command to install it: sudo apt install perl, sudo dnf install perl, or sudo pacman -S perl.
On Windows, TeX Live can’t run from a folder whose name has accented or non-Latin letters. If your user folder has such a name, Oleafly puts TinyTeX in a folder under ProgramData instead. If antivirus holds a file open while TinyTeX moves into place, Oleafly tries again, and if it still can’t finish, wait a moment and retry the install.
MiKTeX and Perl
Section titled “MiKTeX and Perl”MiKTeX’s latexmk is a Perl script, and MiKTeX doesn’t include Perl. Without Perl, Settings marks MiKTeX with latexmk needs Perl, and Oleafly compiles with TinyTeX instead when it is installed. With nothing else to use, the compile stops and gives you three ways forward: install TinyTeX from Settings → Engines → LaTeX, which brings its own Perl, install Strawberry Perl, or switch the project back to Tectonic.
MiKTeX manages its packages in MiKTeX Console, so the Packages list and Find and install don’t apply to it. MiKTeX also doesn’t convert EPS figures while it compiles, so convert them to PDF first or use TinyTeX.
Japanese documents: upLaTeX and pLaTeX
Section titled “Japanese documents: upLaTeX and pLaTeX”Choose upLaTeX or pLaTeX under Compiler (this project) for a Japanese document, or leave the compiler on Auto. Auto picks pLaTeX for jsarticle, jsbook, and jsreport (upLaTeX when the class has the uplatex option), upLaTeX for the uj classes and jlreq, and LuaLaTeX for ltjsarticle and other LuaTeX-ja documents.
Both compilers need TeX Live’s Japanese support. When it’s missing from the managed TinyTeX, or from a TeX Live that Oleafly can write to, the failed compile offers Install Japanese support (about 450 MB). That installs it and compiles again. On other installations the message names the command for your distribution, such as sudo apt install texlive-lang-japanese.
When Tectonic isn’t enough
Section titled “When Tectonic isn’t enough”Some documents need things the built-in Tectonic engine doesn’t do, such as EPS figures or a forced pdftex driver. When the first compile after you open a project, or a compile you start yourself, runs into one of these, the engine dialog opens on its own. When Auto compile or an agent starts the compile, the dialog stays closed and Choose engine appears instead. Choose it to open the dialog. The button stays until the next compile, so it also reopens the dialog after you close it. Where you find it depends on the view:
- After a failed compile, it’s at the right of the preview toolbar while Logs is open. The preview switches to Logs by itself when the compile made no PDF. If a PDF is still showing, choose Logs to see the button.
- In an empty preview, it’s next to Retry compile.
- In editor-only view, when the PDF is in its own window, or after a successful compile, it’s to the left of Recompile.
The dialog is titled This compile needs more than the built-in engine and lists the problems it found. The option marked Recommended comes first:
- Download TinyTeX appears when no working TeX distribution is installed. Its button, Download and use TinyTeX, installs TinyTeX, switches the project to
latexmk, and compiles again. - Use my system LaTeX (latexmk) has Use system LaTeX, which switches the project to
latexmkon the TeX distribution Oleafly found. If the document needs pdfLaTeX, the option reads Use pdfLaTeX on my system LaTeX (latexmk) and its button reads Switch to pdfLaTeX and recompile. With no TeX installed, this option has no button. - Keep using Tectonic has Keep Tectonic, which leaves the project on the built-in engine. When a switch would fix the problems the dialog lists, this option says they won’t go away.
After you keep Tectonic, the same problems no longer open the dialog or show Choose engine for this project on this computer. To switch later, pick a compiler under Compiler (this project).
If the project also needs to run external commands, switching to system LaTeX or TinyTeX allows them too, and the dialog says so before you click. The compiler you pick is saved in the project, so collaborators get the same setup.
Allow external commands
Section titled “Allow external commands”Packages such as minted and PythonTeX, and documents that use \write18, run other programs while they compile. Oleafly blocks that by default. When a compile is blocked, or the log shows that the project needs those commands, a banner above the editor offers Allow external commands.
The built-in engine keeps that block too. Tectonic starts outside the project folder, and the Biber that comes with Oleafly treats a document’s bibliography settings as plain text and skips biber.conf during a compile.
Allow external commands only for a project whose files you trust, because LaTeX can then run any program with your permissions. The permission works only with system LaTeX, and it stays on this computer. It is never stored in project.json or committed to Git, so a coauthor has to allow it on their own computer. In a shared project, Oleafly warns you before turning it on, because anyone who can edit the project could then run programs on your computer when you compile. Switching the project back to Tectonic or deleting it removes the permission. In a folder you opened in place, trust the folder first. Trusting a folder does not allow external commands by itself.
With an engine present, the Preflight panel’s Compile tagged and verify button can produce a tagged PDF with LuaLaTeX and immediately audit it, in one step. Prefer your own toolchain? Preflight’s Prepare for accessible export rewrites your source for tagging and you compile it with any LuaLaTeX from TeX Live 2026, or a TeX Live updated since November 2025, outside the app.
Characters missing from the PDF
Section titled “Characters missing from the PDF”TeX leaves out any character its font has no glyph for, and the compile still succeeds. A Korean, Chinese, or Japanese paragraph can come out blank with no error. Oleafly reads the log after every compile, so when characters go missing you get a notice once per project, the log lists them under Missing characters, and the warning names a few of them.
On the built-in engine and XeLaTeX, the warning also gives a setup for each script it found, using fonts that come with the built-in engine. Paste the one you need into the preamble:
% Korean\usepackage[space]{xeCJK}\setCJKmainfont[AutoFakeBold]{UnBatang.ttf}
% Simplified Chinese\usepackage{xeCJK}\setCJKmainfont[AutoFakeBold]{gbsn00lp.ttf}
% Traditional Chinese\usepackage{xeCJK}\setCJKmainfont[AutoFakeBold]{bsmi00lp.ttf}
% Japanese\usepackage{xeCJK}\setCJKmainfont{ipaexm.ttf}[BoldFont=ipaexg.ttf]The space option keeps the spaces between Korean words, which plain xeCJK drops.
CJKutf8 and the CJK package only work on pdfLaTeX. A project that loads them on the built-in engine compiles without its Chinese, Japanese, or Korean text, so the notice offers Choose engine, which opens the switch to pdfLaTeX. You can also remove the package and its CJK environment and use one of the setups above.
A ctex document on a Mac that uses the Mac’s own fonts can make macOS ask whether to download a font, and the compile waits for your answer. Answer the dialog and compile again, or add fontset=fandol to the \documentclass options.
Other missing characters, such as a symbol or a letter from another script, need a font that has them. Switch to one in the preamble. For Typst projects, see Characters that show as boxes.
The package manager
Section titled “The package manager”Below the engine status sits a filterable Packages list for the LuaLaTeX side, powered by tlmgr:
- Start with the suggested package list, or enter at least two characters and choose Search TeX Live to query the full catalog.
- Search by a package name or a file it contains. Oleafly shows the owning TeX Live package when those names differ.
- Add or Remove a package with one click. Installed rows show whether the package is in the system tree, your personal tree, or both.
- Check the tagging badge before an accessible export: tagging: caution marks packages that can reduce tag quality, while breaks tagging marks known conflicts.
This package manager applies to TeX Live and TinyTeX distributions used by latexmk. Tectonic manages its own package cache. For MiKTeX, use MiKTeX Console.
Recover from a missing file
Section titled “Recover from a missing file”A package is not always named after the file mentioned in a compile log. For example, tikz.sty is installed by the pgf package. Installing a guessed package called tikz would fail.
When a latexmk compile reports a missing file, use Find and install in the message. That covers packages, classes, bibliography styles, font files, babel language files, and TikZ libraries. Oleafly asks TeX Live which package owns the file, installs that package, and recompiles. If no TeX Live package has the file, it probably came with your university or publisher template, so add it to the project from the original template. If several packages have it, the message lists them so you can pick the one your template needs. If the catalog can’t be reached, or the install doesn’t fix the compile, the message says which.
If you try to change a system installation without permission, Oleafly can install into your personal TeX tree instead, and sets that tree up first when it doesn’t exist yet. The package row identifies where it ended up. Removing an owner package also removes the other files it provides, so read the Included in note before removing it.
Keep tlmgr and older TeX Live releases working
Section titled “Keep tlmgr and older TeX Live releases working”tlmgr, TeX Live’s package manager, can fall behind the online TeX Live repository, and then refuses to install anything until it updates itself. For the TinyTeX that Oleafly manages, Oleafly updates tlmgr and repeats the install. On a TeX Live or TinyTeX you installed yourself, the message tells you to run tlmgr update --self.
Once the repository moves on to a new TeX Live year, an older installation can’t install from it. Oleafly then installs from the final archive of your release. If the archive doesn’t have the package either, the message asks you to update TeX Live, or to use Update on the managed TinyTeX in Settings.
Choose where packages come from
Section titled “Choose where packages come from”tlmgr installs packages from a TeX Live repository. The TinyTeX that Oleafly manages uses the nearest CTAN mirror, unless you pick a specific repository, such as your university’s CTAN mirror, under TeX package repository in Settings → Downloads → Sources. A TeX Live you installed yourself keeps its own repository unless you enter an address there. Oleafly hands the address to tlmgr on each run and never changes its saved configuration.
A package search that has to reach the repository can take a while on a slow connection. Oleafly waits up to 10 minutes, and if it gives up, the message names the repository it was waiting on. See Sources tab.
TeX Live from a Linux distribution
Section titled “TeX Live from a Linux distribution”On Debian, Ubuntu, and Fedora, TeX Live comes from the system package manager, so Oleafly doesn’t add packages to it. The Packages list says to use apt or dnf, and a missing file gets a notice with a hint instead of Find and install:
- On Debian and Ubuntu, find the package with
apt-file searchand the file name, or install everything withsudo apt install texlive-full. - On Fedora, the notice gives a
sudo dnf install 'tex(file.sty)'command for the missing file.
When the distribution’s TeX is incomplete, the notice also offers Download TinyTeX (~250 MB), which Oleafly can manage packages for. On Debian and Ubuntu, if you’ve set up a personal tree with tlmgr init-usertree, Oleafly installs packages into that tree.
Add a package from the editor
Section titled “Add a package from the editor”Choose LaTeX packages, the package icon on the LaTeX editor toolbar, to search CTAN without leaving the document. Each result shows whether the document already loads it (In document). In a latexmk project it also shows whether your TeX distribution has it (Installed), and Install adds a missing one with tlmgr. With TeX Live from a Linux distribution, the dialog tells you to install packages with apt or dnf instead.
Add to preamble writes the \usepackage line into the preamble. Options lets you add package options first, and Copy line copies the line instead. A Tectonic project has nothing to install: Tectonic downloads a package the first time the document uses it.
Which engine compiled my PDF?
Section titled “Which engine compiled my PDF?”- Compiler (this project) in the compile menu, the arrow beside Recompile, shows the compiler saved for the current project.
- Tectonic builds use the bundled engine.
- pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, and pLaTeX builds use
latexmkand the TeX distribution marked In use in Settings. - Preflight’s tagged export uses LuaLaTeX and writes to the normal build location.
Templates and packages
Section titled “Templates and packages”Templates declare the packages they need, and Tectonic fetches them on first compile. Templates with on-demand fonts handle those separately. See Templates.