fontspec (Xe/Lua)

fontspec is the package that lets you call any OpenType or TrueType font installed on your system by its name. Writing \setmainfont{Some Font} switches the body typeface, and OpenType features such as ligatures and number styles are available through key=value options. The one firm prerequisite: it requires XeLaTeX or LuaLaTeX — it does not work with the older pdfLaTeX. This page walks through loading it, setting the roman/sans/mono fonts, defining extra families, and selecting fonts by file and by feature.

What fontspec is — and the engine it needs

Traditional TeX could only use fonts in special formats prepared for it, and could not simply reach for the typefaces already on your machine. fontspec is the package that lets you use OpenType and TrueType fonts — installed on the system or placed inside your project — selected by typeface name (or filename). It bridges that selection into LaTeX’s NFSS (font selection scheme), handling the automatic switch to bold and italic and exposing OpenType’s richer typographic features along the way.

Before anything else, note the hard constraint: fontspec only works on XeLaTeX or LuaLaTeX, because those engines handle Unicode and system fonts natively. It cannot be used with pdfLaTeX (pdftex) — try \usepackage{fontspec} under pdfLaTeX and you get an error. Check which engine processes your document and, if needed, compile with lualatex or xelatex. Starting fresh? LuaLaTeX is a safe default, not least for its Japanese support.

Loading it is simply \usepackage{fontspec}. On XeLaTeX and LuaLaTeX it is often already loaded for you (by the class or another package); writing it explicitly does no harm.

Setting the roman, sans, and mono fonts

The document’s three base typefaces are set in the preamble with these three commands. **\setmainfont{…} sets the roman face (the default body font), \setsansfont{…}** the sans-serif (what \textsf and \sffamily select), and **\setmonofont{…}** the monospaced/typewriter face (for \texttt and \ttfamily). The argument is simply the font name as registered on the system.

% xelatex か lualatex でコンパイルする
\documentclass{article}
\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}   % 本文（ローマン体）
\setsansfont{TeX Gyre Heros}    % サンセリフ体
\setmonofont{TeX Gyre Cursor}   % 等幅体
\begin{document}
This is the main font; \textsf{this is sans}; \texttt{this is mono}.
\end{document}

fontspec automatically locates the bold and italic members of a named family and assigns them to \textbf, \textit, and their combination. Write \textbf{…} and \emph{…} as usual and you get the chosen family’s bold and italic. Note too that **placing these commands in the preamble also makes the same fonts apply inside \mathrm-type math** (LaTeX freezes the math fonts at this stage, so only a preamble setting takes effect). The math typeface proper is managed separately, via unicode-math, covered below.

Extra families and one-off fonts

When you need a typeface beyond the roman/sans/mono trio, define a new switch command with **\newfontfamily**. Its first argument is the command name you want to create (a backslash name of your choosing), and the second is the font name.

\usepackage{fontspec}
\newfontfamily\titlefont{TeX Gyre Bonum}
\newfontfamily\quotefont{TeX Gyre Schola}
% ...
\titlefont A heading in Bonum

{\quotefont A quoted passage in Schola.}

A command defined this way, like \titlefont, is a declarative switch (in the same vein as \rmfamily): it applies the font to everything that follows. To limit its scope, wrap it in braces, {\titlefont …}. For a font used only once, you can skip the definition and apply **\fontspec{Font Name}** directly as a declaration on the spot — though since it reloads the font each time, a repeatedly used face is better defined with \newfontfamily.

Selecting by name vs by file

There are two ways to name a font. One is to select it by the typeface name registered with the OS, writing the name directly as in \setmainfont{TeX Gyre Termes}. That is convenient, but the same font must also be present on anyone else’s machine. The other is to select it by file, bundling the font files inside the project — the right choice when you want guaranteed, reproducible output.

For file selection you give the options **Path= (the directory holding the fonts) and Extension=** (the suffix, such as .otf or .ttf), then assign each weight and style with **UprightFont=, BoldFont=, ItalicFont=, and BoldItalicFont=**. The asterisk * written in those values is a placeholder that is replaced by the common filename (the base name) given in the second argument.

\usepackage{fontspec}
% プロジェクト内の fonts/ に置いた OTF を、ファイル名で指定する
\setmainfont{LibreBaskerville}[
  Path       = ./fonts/ ,
  Extension  = .otf ,
  UprightFont    = *-Regular ,
  BoldFont       = *-Bold ,
  ItalicFont     = *-Italic ,
  BoldItalicFont = *-BoldItalic ,
]

Here the base name LibreBaskerville expands into each value, so fonts/LibreBaskerville-Regular.otf, fonts/LibreBaskerville-Bold.otf, and so on are loaded. The table below contrasts the two selection methods.

Turning on OpenType features

OpenType fonts carry typographic features such as ligatures, number styles, and small caps, and fontspec enables them through key=value options. The most useful ones:

• Ligatures= — controls ligatures. Ligatures=TeX enables the TeX-style input conversions** — `-- to an en dash, --- to an em dash, and '' to curly quotes (often on by default in the standard configuration). Others are Common (standard fi, fl, …), Rare/Discretionary (optional ligatures), and Historic`.
• Numbers=** — number style. Combine OldStyle (text figures, with ascenders and descenders) or Lining (uniform-height modern figures) with Proportional (proportional widths) or Monospaced (fixed widths).
• Letters=SmallCaps** — small capitals. Values such as Letters=Uppercase are available too.
• StylisticSet=** — selects, by number, a stylistic set of alternate glyphs that the font provides.
• Scale=** — the scale factor. Besides a number, Scale=MatchLowercase (match the x-height) and Scale=MatchUppercase (match the cap height) are handy for sizing a secondary font to the main one.
• Script= / Language=** — select non-Latin scripts or language-specific shaping rules (e.g. Script=Arabic).

You write these in the option (the bracketed second argument) of the font-setting command. Here is the body font set with TeX-style ligatures and old-style figures:

\usepackage{fontspec}
\setmainfont{TeX Gyre Pagella}[
  Ligatures = TeX ,
  Numbers   = OldStyle ,
]
% サンセリフは本文に大きさをそろえて読み込む
\setsansfont{TeX Gyre Heros}[Scale = MatchLowercase]

To add a feature to just a span rather than the whole document, use **\addfontfeature{…}** (or \addfontfeatures{…} for several). It adds the given feature locally to the current font, taking effect only within the enclosing braces.

In a table we want {\addfontfeature{Numbers={Lining,Monospaced}} 01234 56789} aligned.

Math and Japanese — fonts handled apart

fontspec is responsible for the Latin text fonts of the body. Two areas are handled separately.

One is the math typeface. To bring mathematics onto OpenType fonts as well under XeLaTeX or LuaLaTeX, load the separate **unicode-math package and name an OpenType math font (Latin Modern Math, STIX Two Math, …) with \setmathfont{…}**. It helps to remember that text’s \setmainfont and math’s \setmathfont play distinct roles. See the math-fonts page for details.

The other is Japanese. \setmainfont sets only the Latin face and has no effect on the Japanese one. On LuaLaTeX you use **luatexja-fontspec** — effectively the Japanese counterpart of fontspec — and set Japanese fonts with its “j (Japanese)” commands: **\setmainjfont{…} (Mincho, the Japanese body face), \setsansjfont{…} (Gothic), \newjfontfamily**, and so on, with options largely shared with fontspec. In short you run two parallel tracks: \setmainfont for Latin and \setmainjfont for Japanese. Japanese fonts are covered on their own page.