Install · Create · Compile · Troubleshoot
Build LaTeX documents with Tectonic
Tectonic is a command-line TeX/LaTeX engine. It is distributed as a single executable and can download the TeX support files a document needs as it compiles. You can use it for a one-file document or create a project with a source directory and build configuration.
This walkthrough uses Tectonic’s current project-oriented command interface. In these commands, -X selects that interface. Keep it in the commands below.
1. Install Tectonic
Choose the method that fits your operating system. The package-manager options are convenient when you already use that manager; the official installer scripts and release downloads are alternatives.
Linux
On Linux, the official installer places the executable in the current directory. Move it into a directory on your PATH so you can run it from any project:
curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh
mkdir -p "$HOME/.local/bin"
install -m 755 tectonic "$HOME/.local/bin/tectonic"
tectonic --version
If your shell cannot find tectonic, add $HOME/.local/bin to your shell's PATH, then open a new terminal. Alternatively, install through Conda with conda install -c conda-forge tectonic, or use the executable archive for your platform from the official releases page.
macOS
brew install tectonic
tectonic --version
Homebrew is the simplest option if it is already installed. The official Unix installer also supports macOS.
Windows
Run the official installer in PowerShell. It unpacks tectonic.exe into the current directory; move it to a folder included in your PATH if you want to call it from anywhere.
[System.Net.ServicePointManager]::SecurityProtocol =
[System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString(
'https://drop-ps1.fullyjustified.net'))
./tectonic.exe --version
You can also use Conda on Windows: conda install -c conda-forge tectonic.
Confirm installation with tectonic --help. If that prints the command help, your terminal can find the executable.
2. Create a project
Use tectonic -X new to create a project with a Tectonic.toml file and a starter source file.
tectonic -X new research-note
cd research-note
A new project has this general shape:
research-note/
├── Tectonic.toml # project and build configuration
├── src/
│ └── main.tex # LaTeX source
└── build/ # generated PDF and build files
The generated Tectonic.toml supplies a default output configuration. Keep it in the project root and run project build commands from this directory (or a subdirectory). For an existing folder, run tectonic -X init from that folder to initialize a project.
3. Write a first document
Open src/main.tex and replace its contents with a small document. Save it as UTF-8 text.
\documentclass[11pt,a4paper]{article}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{amsmath}
\usepackage{graphicx}
\title{A Short Research Note}
\author{Your Name}
\date{\today}
\begin{document}
\maketitle
\section{Introduction}
Tectonic compiles this source into a PDF document.
Unicode text works directly: café, naïve, and Δ.
\section{A formula}
The area of a circle is
\begin{equation}
A = \pi r^2.
\end{equation}
\end{document}
Packages belong in the preamble, before \begin{document}. Tectonic’s TeX support bundle supplies many standard packages automatically when they are needed.
4. Compile and open the PDF
From the project root, build the project:
tectonic -X build
The first build may take longer because Tectonic retrieves and caches support files. Later builds reuse its cache. In the default project layout, the PDF is written under build/default/, typically as build/default/default.pdf. You can ask Tectonic to open the built PDF using the system’s default PDF viewer:
tectonic -X build --open
For a standalone .tex file that is not part of a configured project, use the compile subcommand:
tectonic -X compile paper.tex
This writes paper.pdf next to paper.tex by default. To place the PDF in a separate directory, use --outdir:
tectonic -X compile paper.tex --outdir build
5. Keep the PDF updated while editing
Use the project watch command during writing. It builds once, stays active, and rebuilds when an input file changes.
tectonic -X watch
Stop the watcher with Ctrl + C. Open or refresh the PDF in your viewer after a successful rebuild.
6. Add figures and split a long document
Keep assets and included source files inside src/. For example:
src/
├── main.tex
├── chapters/
│ └── method.tex
└── images/
└── pipeline.png
In main.tex, load graphicx and include the figure. Split chapters with \input:
\usepackage{graphicx}
% In the document body:
\input{chapters/method}
\begin{figure}[tbp]
\centering
\includegraphics[width=0.8\linewidth]{images/pipeline.png}
\caption{The processing pipeline.}
\label{fig:pipeline}
\end{figure}
Use paths relative to the source file/project source tree and keep the spelling and capitalization identical to the filenames. Tectonic can retrieve support packages from its bundle, but your own figures and chapter files must exist in the project.
7. Bibliographies
Tectonic can run BibTeX as part of a standalone compile. A basic BibTeX document uses \cite and points to a .bib file:
% In paper.tex
\bibliographystyle{plain}
\bibliography{references}
% In references.bib
@article{knuth1984,
author = {Donald E. Knuth},
title = {Literate Programming},
journal = {The Computer Journal},
year = {1984}
}
Compile with the BibTeX pass enabled:
tectonic -X compile paper.tex --pass bibtex_first
biblatex workflows that use Biber depend on an external Biber executable and compatible versions of Biber and biblatex. For a first bibliography, the built-in BibTeX route above is the simplest place to start.
8. Useful build options
| Command | What it does |
|---|---|
tectonic --version | Print the installed version. |
tectonic -X build --print | Show TeX engine output while building. |
tectonic -X build --keep-logs --keep-intermediates | Save logs and intermediate files to help diagnose a build. |
tectonic -X build --only-cached | Build without network access, using cached support resources only. |
tectonic -X compile paper.tex --synctex | Generate SyncTeX data for editor/PDF source navigation. |
Use tectonic -X build --help or tectonic -X compile --help to see the options available in your installed version.
9. Troubleshooting
- Command not found: ensure the install directory is on
PATH, then restart the terminal. - First build is slow: Tectonic may be downloading support files and preparing its format cache. Subsequent builds should reuse the cache.
- Missing image or input file: check the relative path, extension, capitalization, and that the file is inside the project source tree.
- Missing package: many packages are fetched from the support bundle automatically. A package outside that bundle may need to be added to the project or supplied by a different TeX distribution.
- Need detailed errors: build with
--print --keep-logsand read the first error in the output. - Offline build fails: remove
--only-cachedwhen a required support file has not yet been downloaded, then build once with network access.
10. Tectonic and traditional TeX commands
Tectonic is a TeX engine, not a wrapper around pdflatex. It has its own command interface and build behavior. In particular, the project commands above use the V2 interface (-X), while tectonic paper.tex is the older V1 style. Avoid mixing the two command styles in one set of instructions; for new projects, use the project commands in this guide.