TeXworks

TeXworks is a lightweight, cross-platform LaTeX editor that ships bundled with both TeX Live and MiKTeX. It was built deliberately in the image of TeXShop, the popular macOS editor, to “lower the entry barrier to the TeX world” — which makes it an excellent first editor. This page walks through configuring the typesetting tools, the root-file comment that ties multi-file projects together, and SyncTeX, which links the source to the built-in PDF preview.

What is TeXworks

TeXworks was written by Jonathan Kew — who also created XeTeX. Finding the Windows-oriented integrated environments of the day too elaborate and intimidating for newcomers, he deliberately modeled it on Richard Koch’s TeXShop, the well-regarded macOS editor, bringing its uncluttered feel to Windows and Linux as well. The goal was explicit: to lower the entry barrier to the TeX world. Rather than competing on features, it is designed to reduce the number of places where a beginner can get lost.

Its biggest practical advantage is that there is nothing extra to install: it ships with both TeX Live and MiKTeX, so installing a distribution gives you the editor too. It is built on the Qt GUI toolkit and behaves the same on Windows, macOS, and Linux. The editor itself is Unicode-aware (UTF-8 by default) and provides a modest, well-chosen set of tools — command completion, input assistance, and spell-checking.

The flip side of that simplicity is that TeXworks is not built for elaborate multi-stage builds or heavy project management — such workflows are deliberately kept out of the foreground as too advanced for a beginner. When your setup grows genuinely complex, editors like TeXstudio or VS Code (LaTeX Workshop) are natural next steps. But for getting your very first document to compile, TeXworks is about the shortest path there is.

Configuring the typesetting tools

At the heart of TeXworks is the typesetting dropdown on the left of the toolbar. You pick the engine to run (pdfLaTeX, LuaLaTeX, XeLaTeX, ConTeXt, and so on) and press the green triangle beside it (or Ctrl/Cmd-T); TeXworks compiles the current document and opens the PDF preview. It comes with a set of tools already configured — pdfLaTeX, XeLaTeX, ConTeXt (MkII), plus helpers such as BibTeX and MakeIndex.

You can add your own entries to that dropdown. Open Edit → Preferences → the Typesetting tab; the Processing tools list at the bottom holds the tools, with + to add one, - to remove, and Edit... to modify. Each tool has a Name (the label shown in the dropdown), a Program (the command to run), Arguments (one per line), and a View PDF after running checkbox. Arguments accept variables: $fullname expands to the file being processed, and $synctexoption to the SyncTeX option (covered below).

As one example, here is a pdfLaTeX tool that hands the build off to latexmk. Because latexmk decides for itself how many passes are needed to resolve cross-references and bibliographies, it keeps the TeXworks side simpler. 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 usual route is to typeset with upLaTeX and turn the result into PDF with dvipdfmx. The TeXworks bundled with TeX Live already includes Japanese tools, but if you add one yourself, the easiest approach is ptex2pdf, which wraps both steps. Set Program to ptex2pdf and the Arguments as follows (-u selects upLaTeX, -l the LaTeX format, and -ot passes extra options through to TeX).

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

Set the one you use most as the default typesetting engine at the top of the Typesetting preferences, and newly opened documents will use it. When you need a different engine for a particular file, the magic comment in the next section overrides it.

The root file and magic comments

As a document grows, a common arrangement is to split it into per-chapter files pulled in from a parent with \input or \include. The snag is what happens when you typeset while a child file (say chapter1.tex) is open: the child has no \documentclass and no \begin{document}, so it cannot compile on its own.

The fix is a magic comment. To TeX these look like ordinary comments (anything after %), but TeXworks reads certain lines at the top of a file and changes its behavior accordingly. Put **% !TeX root = ... at the top of a child file pointing at the parent, and typesetting while you edit the child makes TeXworks compile the parent (root) file instead**. The path is written relative to the child file.

% !TeX root = main.tex

\chapter{はじめに}
本文をここに書きます。

There are other magic comments. **% !TeX program = ... chooses the engine for that document — the value is the name of the tool you configured in Preferences, not the executable’s filename. Put it at the top of a Japanese document and the right engine is used even if you forget to switch the dropdown. % !TeX encoding = ... declares the file’s character encoding; since TeXworks defaults to UTF-8**, you usually don’t need it if you write in UTF-8. (% !TeX program also accepts the older spelling % !TeX TS-program.)

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

SyncTeX (forward and inverse search)

TeXworks has a built-in PDF preview based on Qt and the Poppler library, so there is no need to switch to an external viewer like Acrobat — you move between editing and checking in the same window. SyncTeX then links positions in the source and the preview in both directions; it is the synchronization mechanism developed by Jérôme Laurens and others.

It is intuitive to use. To jump from a spot in the source to the matching place in the PDF (forward search), Ctrl/Cmd-click in the source. To go the other way, from the PDF back to the corresponding line in the source (inverse search), Ctrl/Cmd-click in the preview. Being able to hop instantly between “where is this paragraph in the PDF” and “which source line is this” makes revising far smoother.

Happily, this works out of the box. SyncTeX builds its mapping by emitting a .synctex.gz lookup table at compile time, and the standard TeXworks tools turn it on automatically by passing the equivalent of **--synctex=1** (the $synctexoption from the previous section). In your own tools, include $synctexoption in the arguments and synchronization works the same way.