Texmaker exists because its author walked away from another LaTeX editor. Pascal Brachet founded Kile, the LaTeX environment for the KDE desktop, and in 2003 handed its maintenance to a different developer; on 29 May of that same year the first Texmaker release appeared — a cross-platform IDE written in Qt alone and tied to no particular desktop. This page walks through the master document mechanism that holds a multi-file manuscript together, the Quick Build chain sitting behind F1, the structure view that grows as you type, and how Texmaker differs from TeXstudio, which is itself a fork of Texmaker.
The author of Texmaker also founded Kile
The connection is recorded on the Kile side. The first name in Kile’s AUTHORS file is Pascal Brachet, and the kile(1) manual page states that “Kile was written by Pascal Brachet and Jeroen Wijnhout.” In an October 2003 interview Wijnhout described contacting Brachet because he wanted to add features: “It turned out that he wanted to stop the development of Kile. So I got more than I bargained for, the project was in my hands now.” What Brachet let go of was an editor welded to KDE; what he wrote instead was Texmaker, which needs no KDE libraries and runs on Qt alone. The same idea, detached from a desktop environment.
The result is an editor that packs a whole IDE into one window: structure view on the left, source in the middle, log and messages below, PDF preview on the right. The licence is GPL v2, the toolkit is Qt, and builds for Windows, macOS, and Linux come from the same author. Inside you get Unicode with a choice of encodings, code folding for \part, \chapter, \section and \begin{...}…\end{...} blocks, a palette of some 370 mathematical symbols, a built-in PDF viewer with continuous scrolling, spell checking, completion, rectangular block selection, search across folders, regular expressions, Asymptote support, and user-defined snippets — which is to say, very nearly everything TeXworks deliberately left out.
Texmaker vs TeXstudio: TeXstudio is a fork of Texmaker
They look alike because one branched off the other’s source. A project split from the Texmaker codebase in 2008 and published its first release in February 2009 under the name TexMakerX. The similarity of the names caused enough confusion that in June 2011 it was renamed TeXstudio. That is why the screen layout and the shape of the settings still feel like siblings. What the fork added afterwards is mostly editing machinery — grammar checking, mirror cursors, stronger folding and completion — while Texmaker stays what the original was: fewer settings, more directness. Whichever you learn first transfers to the other, so in practice start with the lighter one, Texmaker, and move to TeXstudio when it stops being enough.
The master document: holding a multi-file manuscript together
Once you split the manuscript into per-chapter files, the first thing to do is name a master document from the Options menu. That is the pivot of multi-file work in Texmaker. In master mode the build always starts from the master no matter which file is in front of you: press F1 while editing chapter3.tex and what gets compiled is main.tex. Leaving the mode happens from the same Options menu, and because entering and leaving are in one place, it is hard to lose track of which state you are in.
Master mode changes what the tokens in a command’s arguments mean. The one you use most in Texmaker’s settings, %, stands for “the file name without its extension” — but in master mode it expands to the master document’s name. That is precisely why a separate token, #, exists: it gives you the file currently open, even in master mode. Not knowing the difference between the two is what trips people up the moment they want to run something per chapter. The same fields accept @ for the current line number and ! for the current directory.
| Token | What it expands to |
|---|---|
% | the file name without its extension — the master document’s name when in master mode |
# | the name of the file currently open, without extension — unchanged even in master mode |
@ | the current line number — used when handing a forward search to an external viewer |
! | the current directory |
%% ## @@ !! | how to write the character itself — doubling a token yields one literal copy of it |
Quick Build: deciding what F1 runs
Building in Texmaker is decided by two sections under Options → Configure Texmaker (called Preferences on macOS). Commands holds what each command actually is — with which arguments pdflatex or dvipdfmx is launched — and Quick Build holds the order in which they run. Because the division is clean, a change like switching to Japanese engines, which keeps the order and replaces only the contents, happens in one place. What launches the chain is the toolbar button, or the F1 key.
The Quick Build section lists the common combinations as radio buttons, and you pick one. To assemble your own, use the User field at the bottom and join the commands with |.
- PdfLaTeX + View Pdf — go straight to a PDF with pdfLaTeX and display it. The shipped default; enough for mostly-Western text.
- LaTeX + dvips + View Ps — go via a DVI, turn it into PostScript with dvips, and display that.
- LaTeX + dvipdfm + View Pdf — go via a DVI and turn it into a PDF with dvipdfm(x). The standard route for Japanese.
- User — chain whatever commands you like with
|in the field above to build a flow of your own.
The PdfLaTeX field in the Commands section reads, by default, roughly as follows. -interaction=nonstopmode stops LaTeX from halting at an interactive prompt when it hits an error, and -synctex=1 makes it emit the information SyncTeX needs later. Both are worth keeping whichever route you choose.
pdflatex -synctex=1 -interaction=nonstopmode %.texIf you would rather have the bibliography, the index, and the rerun count handled for you, one option is to put a single call to latexmk in the Quick Build User field. latexmk resolves the dependencies and runs each step as many times as needed, so there is nothing left to lay out here. Configuring latexmk itself is the subject of another page.
latexmk -pdf -synctex=1 -interaction=nonstopmode %.texConfiguring builds for Japanese: upLaTeX and LuaLaTeX
The long-standing standard for Japanese is upLaTeX + dvipdfmx, and in Texmaker it takes changes in exactly two places. In the Commands section, rewrite the LaTeX field to uplatex and the Dvipdfm field to dvipdfmx, then select “LaTeX + dvipdfm + View Pdf” under Quick Build. Press F1 and the run goes upLaTeX → dvipdfmx, ending with the PDF on screen. -kanji=utf8 pins the input encoding to UTF-8 and -no-guess-input-enc turns off encoding guessing. Forget -synctex=1 here and you get the confusing symptom where everything works except inverse search.
uplatex -no-guess-input-enc -kanji=utf8 -synctex=1 -interaction=nonstopmode %.texdvipdfmx %.dviThe other path is LuaLaTeX, which takes fewer steps if you are starting a Japanese document from scratch and goes straight to a PDF without a DVI. Check that the LuaLaTeX field under Commands is in order and put lualatex -synctex=1 -interaction=nonstopmode %.tex in the Quick Build User field (the Japanese typesetting itself is handled by the luatexja package or the ltjsarticle class). If you would rather keep all configuration in one place, describe the upLaTeX or LuaLaTeX flow in a .latexmkrc and have Texmaker do nothing but call latexmk.
The structure view, completion, and the wizards
The Structure view down the left is a map of the document that refreshes as you type. Headings (\section and friends), labels (\label), and the files pulled in through \input and \include are laid out in a hierarchy, and clicking an entry jumps there. In a project with a master document, the contents of the chapter files join the same tree, so even a long manuscript can be navigated without losing the overall picture. This surface for seeing the whole is what TeXworks does not have, and it is one of the things that makes Texmaker an IDE.
Completion cuts keystrokes. Type \ followed by a letter and a list of candidate commands appears, narrowing as you add letters; commands that take arguments show placeholders, so you fill the braces one after another. It is not only command names. Write \ref{...} or \pageref{...} and the labels present in the document are offered; \cite{...} offers the keys from your bibliography database — the pause for half-remembered names disappears. On top of that come the wizards: Quick Start settles the \documentclass, the paper size, and the encoding in one dialogue, while Tabular, Tabbing, and Array (which lets you choose among array, matrix, and pmatrix) write out the scaffolding nobody remembers verbatim.
What to check, in order, when F1 fails
Before rewriting the Quick Build chain, split the question in two: what does the log say, and could the external command start at all? The two have entirely different causes and cures, yet on screen both look like “I pressed F1 and no PDF appeared.” In particular, Could not start the command is not a LaTeX error at all — it means Texmaker could not find the executable — so no amount of re-reading the log will explain it. The order is the same for a long thesis and a short report.
- Start in the Messages / Log file panel and find the first error. If the line numbers are clickable, jump straight to the offending source.
- For
Could not start the command, runpdflatex --versionoruplatex --versionin a terminal and fix PATH; Texmaker’s settings are not involved. - If only the PDF refuses to refresh, check whether the built-in viewer is holding an old file and whether the Quick Build you chose actually includes View Pdf.
- If only Japanese fails, confirm that the LaTeX and Dvipdfm fields form a consistent upLaTeX + dvipdfmx pair.
The two conditions for SyncTeX to work
Only two things are needed: -synctex=1 on the compile command, and the PDF opened in the built-in viewer. The first makes LaTeX emit the synchronisation file (.synctex.gz); writing the commands as shown above is enough. The second means choosing the built-in viewer as the Pdf Viewer in the Commands section, and enabling Embed as well if you want it docked inside the main window. Open the PDF in an external viewer and the jumps stop working in both directions.
The gestures are plain. As the manual describes it, with -synctex=1 on the compile command the built-in viewer moves by itself to the position in the PDF matching the current line — that is forward search, and there is no button to press. Inverse search is the other way: right-click on a word in the built-in viewer and choose from the context menu, and the editor jumps to the matching line. The synchronisation mechanism itself is covered on its own page.