TeXworks

“The man who wrote XeTeX then wrote an editor with almost no features.” That is where TeXworks begins. Having given TeX both Unicode and the system’s own fonts, Jonathan Kew turned to a different problem: the number of places where someone starting out in LaTeX can get lost. The title of his TUG talk was “TeXworks: lowering the barrier to entry.” So TeXworks has no project manager, no build script, no file tree down the side. One window, one button, and exactly one thing to choose — the engine. This page covers which distributions actually bundle TeXworks (the answer depends on your platform, and a great many write-ups get it wrong), how to rewrite its single configuration screen, the typesetting tools, and how one line of % !TeX root stands in for project management.

TeXworks was written by the author of XeTeX

TeXworks was written by Jonathan Kew, the author of XeTeX. His model was Richard Koch’s TeXShop, long the default choice on the Mac. Kew judged that TeXShop’s plain arrangement — source and PDF side by side in a single window — works well for beginners, and TeXworks brings that feel to Windows and Linux. The integrated environments then available on Windows simply had too many buttons for someone meeting LaTeX for the first time. Kew’s answer was not to add features but to reduce the number of decisions.

That scarcity is concrete. Open TeXworks and you get an editing surface, an engine dropdown with a green triangle beside it on the toolbar, and a second pane showing the PDF. No file tree, no chapter outline, no build configuration file. The interface is written in Qt, so it looks the same on Windows, macOS, and Linux; the licence is GPL v2 and the default encoding is UTF-8. The toolkit inside is minimal too — command completion, input assistance, spell checking — and when that is not enough, optional Lua and Python scripting plugins let you bolt on processing of your own (they are build-time options; Lua is on by default, Python off). The version number is worth noting: more than a decade after the first release it is still in the 0.6 series, with a small update appearing around February most years. Piling on features on the way to a 1.0 was never the plan.

Which distributions bundle TeXworks

On Windows you almost certainly have it already: both the MiKTeX installer and the Windows installer for TeX Live put TeXworks on your machine. On macOS and Linux it does not come with the distribution. That TeX Live ships only the Windows executable is not a guess — it is written in TeX Live’s own package database, texlive.tlpdb. The description of the texworks package reads “TeX Live includes executables and support files only for Windows,” and the collection that wraps it, collection-texworks, is titled “TL includes only the Windows binary.”

# from texlive.tlpdb, the package database TeX Live installs from
name texworks
category TLCore
shortdesc friendly cross-platform front end
longdesc TeX Live includes executables and support files only for Windows.
postaction shortcut type=menu name="TeXworks editor" \
           cmd=TEXDIR/bin/windows/texworks.exe

This is where the confusion starts. TeX Live also ships a short note at texmf-dist/doc/texworks/README which says that TeX Live includes a Windows binary and MacTeX includes a macOS one. But that README was written in 2009, and what the installer actually acts on is the database. The GUI editor MacTeX provides today is TeXShop, not TeXworks. On Linux, TeXworks is decoupled from TeX Live entirely and arrives as your distribution’s own texworks package. In short, the sentence “TeXworks comes with TeX Live” is true on Windows and only on Windows.

The typesetting dropdown and Processing tools

Everything TeXworks knows about building lives in a single dropdown at the left of the toolbar. Choose the engine (pdfLaTeX, XeLaTeX, LuaLaTeX, ConTeXt, and so on), press the green triangle beside it or Ctrl/Cmd-T, and the open document is compiled and the PDF preview appears. Helpers such as BibTeX and MakeIndex are registered from the start, so an ordinary document reaches a PDF without your ever opening the settings.

You can rewrite that list yourself. Edit → Preferences → the Typesetting tab puts the Processing tools list in its lower half, with + to add, - to remove, and Edit... to modify. A tool has only four parts: the Name shown in the dropdown, the Program to launch, the Arguments, and a View PDF after running checkbox. The most common accident here is in the Arguments, which take one argument per line. This is not a shell command line, so typing -interaction=nonstopmode %.tex all on one line hands the whole string over as a single argument and the engine goes looking for a file with a very strange name.

The Arguments accept TeXworks variables. $fullname, which names the file being processed, is the familiar one, but there are five in all; being able to pull out just the extension or just the directory is what makes DVI routes and helper tools expressible. Variables are expanded immediately before the tool is started.

Registering latexmk as a single tool

What TeXworks lacks is the brain that decides how many passes to run. Cross-references that stay ??, a \tableofcontents that is always one revision behind — these are all questions of how many times you compiled, and TeXworks does not count for you. The standard move is to hand that judgement entirely to latexmk and keep a single tool on the TeXworks side that calls it. Set Program to latexmk, enter the Arguments one per line as below, and tick View PDF after running.

-e
$pdflatex=q/pdflatex $synctexoption %O %S/
-pdf
$fullname

For Japanese, the long-established route is to typeset with upLaTeX and produce the PDF with dvipdfmx. The TeXworks bundled with TeX Live already carries Japanese tools, but if you build one yourself, ptex2pdf is the shortest path because it wraps both stages. Set Program to ptex2pdf and the Arguments as follows (-l selects the LaTeX format, -u selects upLaTeX, and -ot introduces extra options passed through to TeX). Configuring latexmk itself is the subject of another page; what matters here is only how to call it.

-l
-u
-ot
-kanji=utf8 -no-guess-input-enc $synctexoption
$fullname

Whichever tool you use most often, set it as the default typesetting engine at the top of the Typesetting tab; newly opened documents will then use it. When a particular file needs a different engine, the magic comment in the next section overrides the default.

% !TeX root: the one line that replaces project management

The moment you split a document into per-chapter files pulled in from a parent with \input or \include, the absence of any “project” concept in TeXworks becomes the problem. Typeset while chapter1.tex is open and the compile fails, naturally enough, because that file has neither \documentclass nor \begin{document}. Another editor would have you create a project and register a master document; the TeXworks answer was to write one line at the top of the file.

% !TeX root = main.tex

\chapter{Introduction}
The body of the chapter goes here.

To TeX it is just a comment — everything after % — but TeXworks reads the first few lines of a file and changes its behaviour accordingly. With that line in place, typesetting while you edit the child makes TeXworks compile the parent (root) file instead. The path is written relative to the child. The elegance is that the information lives in the file rather than in a setting: project files break when the machine changes, whereas a comment line goes into the repository and keeps working on a co-author’s machine. The convention comes from TeXShop, and editors other than TeXworks read the same line.

There are other magic comments. % !TeX program = ... pins the engine used for that document. Note that what goes here is not the executable’s filename but the Name of the tool as registered in Preferences — not pdflatex, but the label exactly as it appears in the list. The older spelling % !TeX TS-program = ... means the same thing. % !TeX encoding = ... declares the file’s character encoding, though since TeXworks defaults to UTF-8 you rarely need it if you write UTF-8. Putting % !TeX program at the top of a Japanese document means the right engine runs even when you forget to change the dropdown.

% !TeX program = upLaTeX (ptex2pdf)
% !TeX encoding = UTF-8
\documentclass{ujarticle}
\begin{document}
\input{chapter1}
\end{document}

TeXworks vs TeXstudio, and when to move on

The difference is not the number of features but the design goal. TeXworks is optimised for reducing the places where you can get lost; TeXstudio, Texmaker, and Kile are optimised for putting everything you might need within reach. Saying “TeXworks has fewer features” is therefore a description of its specification, not a verdict, and the right axis for comparison is what is currently costing you time. When two or more of the following are true, it is time to think about moving.

• The file count has grown and you keep tripping over child files where you forgot the % !TeX root line.
• You are working with a bibliography database and spend real time hunting \cite keys in another window.
• The build is no longer a single pdfLaTeX run, and the Processing tools list has filled up with entries.
• The same manuscript now has to be produced with more than one engine — pdfLaTeX and LuaLaTeX, say.

Reading the log and the auxiliary files

Precisely because nothing else clutters the screen, TeXworks is a good place to build the habit of reading the log. The output panel after a typeset run tells you more than whether a PDF appeared: unresolved references, missing packages, and images that failed to load all show up verbatim. A line such as ! Missing $ inserted or ! Undefined control sequence is the first error, and the line number just beneath it is the real clue. TeXworks is designed to make you read rather than to halt on your behalf, so skipping this panel throws away half of what it offers.

• If references stay ??, typeset once more with the same tool so .aux is refreshed (a latexmk tool does this for you).
• Delete .aux and .toc only after a major reshuffle of the table of contents or the bibliography, then rebuild. Keeping them is normally faster.
• When an image does not appear, compare the filename in the log against the real path. Avoid spaces and non-ASCII characters in filenames.
• When the Processing tools list gets crowded, move the build knowledge into .latexmkrc and go back to a single latexmk tool.

SyncTeX settings: forward and inverse search

TeXworks carries a built-in PDF preview based on Qt and Poppler, so editing and checking happen in the same window without launching an external viewer. Forward search — from a spot in the source to the matching place in the PDF — is Ctrl/Cmd-click in the source; inverse search, back from the PDF to the source line, is Ctrl/Cmd-click in the preview. No configuration is needed, because the stock tools already carry $synctexoption in their Arguments, which is what makes the engine write the .synctex.gz lookup table the jumps rely on. If synchronisation fails in a tool you wrote yourself, check first that you did not omit that variable. How SyncTeX works internally is the subject of its own page.