TeXShop (Mac)

TeXShop went out on the internet on 23 July 2000 — eight months before Mac OS X 10.0 was on sale. Richard Koch, a mathematician at the University of Oregon, had written a LaTeX front end for an operating system that did not officially exist yet, and the bet paid off: twenty-six years later TeXShop is still the editor MacTeX drops into /Applications/TeX/, still free, still GPLv2, still macOS only. This page is about what that history left behind — an engine pop-up that is really just a folder of shell scripts, the % !TEX lines that pin one file's settings, ⌘-click SyncTeX — and about the point where TeXShop stops being the right tool.

Why TeXShop previews a PDF and never a DVI

Because macOS itself draws in PDF. When Apple bought NeXT at the end of 1996 it dropped NeXTSTEP's Display PostScript imaging model and rebuilt the Mac's graphics layer, Quartz, on PDF — which, in Koch's own words, made PDF fundamental to the system, easy to create and trivial to display. A DVI previewer would have been months of work; a PDF previewer was almost free. He had also just found pdfTeX, then at version 0.14, which turned .tex straight into .pdf with no dvips step in between. So the whole shape of TeXShop — a source window, a preview window beside it, pdflatex in the middle — fell out of a decision Apple made about how to draw rectangles on a screen.

The first public releases went out in July 2000, while Mac OS X was still a public beta, and they carried one spectacular flaw that was not Koch's fault. Apple's PDF code could not yet read embedded fonts, so a TeX document set in Times displayed beautifully — while every equation in it came out as blank space. That was the one thing a mathematician needed. At the 2000 developer conference Koch hurried back to his motel with the newest beta, installed it, ran TeXShop, and found the fonts still missing; Apple fixed it in time for the non-beta release of March 2001. In 2002 TeXShop 1.19 won an Apple Design Award — in a category for open-source ports, which raised eyebrows on the Mac TeX mailing list, since TeXShop had never been a port of anything. And when Jonathan Kew, the author of XeTeX, wanted TeX to feel this approachable on Windows and Linux, he built TeXworks explicitly on the model of what he called Dick Koch's award-winning TeXShop.

Installing TeXShop: it arrives inside MacTeX

There is no separate TeXShop installer to hunt down — MacTeX brings it. MacTeX-2026 carries TeX Live 2026, puts the distribution under /usr/local/texlive/2026/, and drops five applications — TeXShop, TeX Live Utility, LaTeXiT, BibDesk and hintView — into /Applications/TeX/. It requires macOS 11 Big Sur or later and runs natively on both Intel and Apple silicon. What matters for everything below is that TeXShop contains no TeX at all: it is a front end, and every typeset simply runs pdflatex, lualatex or latexmk out of /Library/TeX/texbin. Throw TeXShop away and your TeX still works from Terminal; throw /usr/local/texlive/ away and TeXShop cannot set a single line.

The two halves update on separate clocks, which trips people up. Package updates come through TeX Live Utility, the second app in that folder: open it and it offers everything CTAN has changed since you last ran it. TeXShop itself is updated from Koch's page at the University of Oregon. Version 5.57 (October 2025) requires macOS 10.13 High Sierra or later and runs all the way up to Tahoe. For macOS 26 Tahoe, TUG ships an extra installer that adds TeXShop 5.58 beside 5.57 rather than replacing it; 5.58 is the same program recompiled on Tahoe, which is what gives an application Apple's Liquid Glass appearance. Several years of TeX Live can coexist under /usr/local/texlive/, and TeX Live Utility's Configure menu is where you choose the active one.

The Typeset button, ⌘T, and the engine pop-up

⌘T saves the file and typesets it; the pop-up beside the Typeset button — labelled Program in the toolbar — decides what actually runs. Those menu entries are not built into the application. TeXShop reads the folder ~/Library/TeXShop/Engines/ and lists one item per .engine file it finds there, and an .engine file is nothing but a short shell script that receives the file name as $1. The one shipped as LuaLaTeX.engine is four lines long. This is the single most useful thing to know about TeXShop: anything you can type in Terminal, you can put in that menu. The menu item TeXShop → Open ~/Library/TeXShop takes you straight to the folder.

#!/bin/tcsh

set path= ($path /Library/TeX/texbin /usr/texbin /usr/local/bin)
lualatex -file-line-error -synctex=1 "$1"

Two flags in that script are there for a reason and belong in any engine you write yourself. -synctex=1 produces the .synctex.gz file that makes ⌘-click work in both directions. -file-line-error changes the shape of every error message from TeX's traditional l.42 to ./main.tex:42: Undefined control sequence. — a file name and a line number you can jump to. TeXShop's built-in LaTeX command already passes both (pdflatex --file-line-error --synctex=1), so the defaults are sane; it is homemade engines that quietly lose the ability to sync. Which engine greets a new document is remembered from your last choice, and Preferences → Typeset → Default Command decides the underlying route — pdfTeX, TeX + DVI, or a personal script — when no engine is named.

Why one Typeset is not enough: pdflatexmk and the rerun warning

If the console ends with LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right., the PDF on your screen is one run out of date. LaTeX writes labels, page numbers and the table of contents into .aux and .toc on one pass and reads them back on the next, so a document with cross-references genuinely needs two runs, and one with a bibliography needs bibtex or biber in between. Pressing ⌘T three times does work. But counting runs is not a job for a human: latexmk compares the auxiliary files and reruns exactly as often as necessary, index and bibliography passes included.

TeXShop ships those engines but keeps them switched off, so this is a two-minute setup you do once. Open ~/Library/TeXShop/Engines/Inactive/Latexmk/ and move pdflatexmk.engine — or lualatexmk.engine, or xelatexmk.engine — two folders up into ~/Library/TeXShop/Engines/, then restart TeXShop; the name appears in the Program pop-up. There is a shortcut for trying it first: the menu item Typeset with Alternate Engine runs whatever is set in Preferences → Engine → Alternate Engine, and that field already says pdflatexmk out of the box. When a build goes strange — a stale .aux, a label that will not resolve — hold Option and the Typeset item becomes Trash Aux & Typeset (⌥⌘T), which throws the intermediate files away first.

The % !TEX lines: root, TS-program and encoding

A file can carry its own settings, and in a shared project it should. Put a % !TEX line within the first twenty lines of a document and TeXShop reads it; LaTeX ignores it, because everything after % is a comment. That asymmetry is the whole trick: the file tells the editor how to build it and travels to a co-author's machine with the instructions attached. Three directives do almost all the work.

% !TEX root = ../thesis.tex
% !TEX TS-program = lualatexmk
% !TEX encoding = UTF-8 Unicode

% This chapter has no preamble of its own.
% Pressing Typeset here builds ../thesis.tex instead.
\chapter{Method}
\label{chap:method}

Of the three, root is the one that saves an afternoon. Split a thesis into chapters, press ⌘T inside chapter3.tex without it, and TeX starts reading a file that has no \documentclass, which ends at the first line of body text as ! LaTeX Error: Missing \begin{document}. The path is relative to the chapter file, so a chapter living in chapters/ points back with ../thesis.tex. The same line is what tells SyncTeX which chapter and which line a ⌘-click in the PDF belongs to. Add it the moment you split a document, not the first time something breaks.

Encoding: why a .tex file opens as garbage, or refuses to open

Since TeXShop 4.00 the factory default has been Unicode (UTF-8), and that is the right answer for anything written today; the setting lives in Preferences → Source → Encoding. Text files carry no header announcing how they are encoded, so TeXShop cannot guess and deliberately does not try. When a file is not valid UTF-8 — a collaborator in Western Europe writing umlauts in IsoLatin9, an old manuscript out of a lab archive — decoding fails and TeXShop offers to reopen it in a fallback encoding, IsoLatin9, which is fixed and not configurable. Take the offer, read the \usepackage[...]{inputenc} line to learn what the file really is, close it without saving, reopen it with the right encoding from the Open dialog — and only then add a % !TEX encoding line, so that nobody has to do this twice.

TeXShop's Japanese support arrived by exactly this route, and it is the best story in the program's history. On Mac OS 9, Japanese fonts drew the backslash as a yen sign and the yen key on a Japanese keyboard emitted a backslash byte, so \section and ¥section were the same bytes and TeX never noticed. Then Unicode separated the two characters, keyboards began producing a real yen sign, and Japanese TeX responded by accepting ¥ as the TeX escape character — which left TeXShop mangling files. Koch heard for about a year that Japanese users were having trouble before Seiji Zenitani emailed both the explanation and the code; Zenitani also contributed the Japanese localisation. He then pointed Koch at Mitsuhiro Shishikura, a mathematician, who sent a cleaner fix for the yen problem and, almost in passing, the magnifying glass for the preview window and the macro editor. Both names still stand in the credits on TeXShop's page, alongside Yusuke Terada and Isao Sonobe.

Japanese and CJK: LuaLaTeX, or upLaTeX with dvipdfmx

For a document started from scratch today, pick LuaLaTeX in the Program pop-up and the question is settled. It reads UTF-8 natively and addresses the fonts already installed on the Mac, so with the luatexja package or a class like ltjsarticle it sets Japanese with no extra machinery. For Chinese and Korean, XeLaTeX with xeCJK or ctex occupies the same position. The one road to avoid here is pdflatex: pdfTeX predates convenient access to Unicode fonts, and pushing CJK through it means the old CJK package and preconverted fonts — not a path anyone chooses on purpose today.

The other road is upLaTeX with dvipdfmx, the combination Japanese publishing has used for decades and the one an inherited departmental template usually assumes. TeXShop has a checkbox for it: Preferences → Engine → pTeX support (for Japan) switches the built-in commands over to the pTeX family, and ~/Library/TeXShop/Engines/Inactive/Latexmk/ also holds dvipdfmxmk.engine for driving that route through latexmk. A hand-written engine for it is a single line, and that line shows how the pieces connect: ptex2pdf is the script shipped with TeX Live that runs TeX and then the DVI-to-PDF step, -l selects LaTeX rather than plain, -u selects the Unicode-capable upTeX, and -ot forwards options to the engine itself.

#!/bin/sh

# a hand-written engine: upLaTeX, then dvipdfmx, with SyncTeX enabled
ptex2pdf -u -l -ot "-synctex=1 -file-line-error" "$1"

The choice matters more than it looks, because it is not cheap to reverse. A class written for upLaTeX (jsarticle, ujarticle) will not compile under LuaLaTeX, and vice versa — and neither will half the macros in a departmental thesis template. Decide once, at the start, and if you inherited a template that names its engine, follow it rather than migrating a week before the deadline. The line that makes that decision survive on somebody else's Mac is % !TEX TS-program at the top of the master file.

SyncTeX: ⌘-click to jump between source and PDF

⌘-click, and that is the entire interface. ⌘-click a word in the preview and the source window jumps to the line that produced it (inverse search); ⌘-click a line in the source and the preview scrolls to the matching spot (forward search). TeXShop has supported SyncTeX since version 2.18, and every standard engine passes -synctex=1, so it works untouched — the .synctex.gz file appearing next to your PDF at each typeset is the proof. If it ever stops working, check three things: that the file has been typeset at least once since the last edit, that a homemade engine has not dropped -synctex=1, and that Preferences → Typeset → Sync Method is on the SyncTeX setting rather than the legacy pdfsync one.

Proofreading is where this changes how you work. The loop of reading the PDF, spotting a broken sentence, then hunting through three hundred lines of source for it disappears entirely: you ⌘-click the sentence and start typing. In a multi-file project, though, the jump only lands correctly if every child file carries its % !TEX root line — without it TeXShop does not know which master produced the page, and the click goes nowhere. It is the same line that makes ⌘T work from inside a chapter, which is exactly why it is worth adding the moment a document is split.

TeXShop, or TeXworks, TeXstudio, VS Code: which to use

TeXShop wins on the thing beginners actually need, which is that there is nothing to configure: install MacTeX, open a file, press ⌘T. It is also unusually pleasant once you are past that — Command Completion on the Esc key, macros that can be AppleScript, editable themes — and the engine folder means it never refuses to run a command it has not heard of. Its limits are just as clear. There is no project sidebar, no built-in version control, no compile-as-you-type, and no build at all on a machine that is not a Mac.

• On a Mac, working alone, unwilling to spend time on setup: TeXShop is the right default — the Program pop-up plus % !TEX lines cover nearly everything.
• Need the same feel on Windows or Linux: TeXworks, which was modeled on TeXShop and transfers almost unchanged.
• Want a structure browser, symbol panels and reference management in one window: TeXstudio or Texmaker.
• Already writing in an editor with Git, LSP and a terminal: VS Code with LaTeX Workshop, keeping MacTeX underneath.
• Co-authoring with people who will not install anything: Overleaf as the shared place, TeXShop as your local copy for the final pass.