Comprehensive TeX Archive Network

Direc­tory macros/latex/contrib/fontspec



The fontspec pack­age pro­vides an au­to­matic and uni­fied in­ter­face for load­ing fonts in LaTeX. XeTeX and LuaTeX (the lat­ter through the luaotfload pack­age) al­lows a di­rect in­ter­face to fonts which may be loaded by their name rather than file­name, so no man­ual font in­stal­la­tion is re­quired.

This pack­age also pro­vides ac­cess to the large num­ber of font fea­tures avail­able with AAT and OpenType fonts, in­clud­ing up­per and lower case num­bers, pro­por­tional and monospaced num­bers, swash let­ters, lig­a­ture con­trol, and many oth­ers.

See the doc­u­men­ta­tion fontspec.pdf for full in­for­ma­tion.

Re­lease ver­sions of fontspec are avail­able from CTAN: <http://www.ctan.org/pkg/fontspec>

Devel­op­ment and his­tor­i­cal ver­sions are avail­able from Github: <http://github.com/wspr/fontspec>

Please of­fer sug­ges­tions and file bug re­ports in the is­sue tracker: <http://github.com/wspr/fontspec/is­sues>

Ta­ble of Con­tents

  • Sum­mary of user com­mands
  • Change his­tory ("what's new?")
  • In­stal­la­tion in­struc­tions
  • Li­cense de­tails

Sum­mary of user com­mands

Font fam­i­lies may be se­lected in­di­vid­u­ally with the com­mand

\fontspec{<font name>}[<font options>]

Com­mands for se­lect­ing fonts ef­fi­ciently through a doc­u­ment are cre­ated with

\newfontfamily\myfamily{<font name>}[<font options>]
\newfontface\myfont{<font name>}[<font options>]

De­fault doc­u­ment fonts are se­lected with

\setmainfont{<font name>}[<font options>]
\setsansfont{<font name>}[<font options>]
\setmonofont{<font name>}[<font options>]

Fea­tures to be used for ev­ery sub­se­quently de­fined font are spec­i­fied with

\defaultfontfeatures{<default font options>}
\defaultfontfeatures+{<add to default font options>}
\defaultfontfeatures[<font name>]{<default font options for "font name">}
\defaultfontfeatures+[<font name>]{<add to default font options for "font name">}

Fea­tures may be added to the font cur­rently in use with

\addfontfeatures{<font options to add>}
\addfontfeature{<...>} does the same thing

Change his­tory

  • v2.5a (2016/02/01) "bugs fixed"
* Rather embarrassing bug fix! (`unicode-math` was broken.)
* Remember to add the `fontspec.cfg` file to the distribution.
* Remove `+trep` from `Ligatures=TeX` (no longer necessary).
* Add some basic tests using `l3build`; more to come.
* Simplify some internal Lua code and package loading code.
  • v2.5 (2016/01/30) "TL2016 re­lease"
* Provide a new Unicode font encoding ("TU") to replace EU1/EU2 and xunicode. If this causes problems, load fontspec with the `[euenc]` option to revert to the old behaviour.
* New command `\emfontdeclare` for defining font shapes when arbitrarily nesting the `\emph` command.
* Allow slanted small caps and better internal methods for "combining" font shapes; this fixes a few bugs.
* Incorporate "new" font script tags for Indic fonts. E.g., when selecting `Script=Bengali`, fontspec will first query the font for the `bng2` OpenType script, and if not found select `beng`.
* Restrict some font features from being able to be used within `\addfontfeatures` that were causing some font-loading confusion.
* Fixed behaviour in which `\baselineskip` and `\f@size` would (possibly) change values after loading the packge.
* Remove copy of `fixltx2e`'s code for footnote symbols; handled by LaTeX2e now.
* Deprecate `ExternalLocation` for the simpler (and identical) `Path` option.
* Improvement to some warnings/info messages.
* Improve structure of code.
  • v2.4e (2015/09/24)
* Allow `[Path=...]` to be specified for individual font faces.
* Continue to normalise naming with expl3. (Ongoing.)
  • v2.4d (2015/07/22)
* Rename an internal expl3 function or two.
  • v2.4c (2015/03/14)
* v2.4b was never released, sorry!
* This time *really* fix `\@fnsymbol` and avoid overwriting it if already fixed.
* Fix "`Renderer=Graphite`" (off-by-one error).
* Fix some edge cases for `\aliasfontfeature`.
  • v2.4b (2014/08/23)
* Improve backwards compatibility w.r.t. recent argument order change;
  specifically, if an optional argument is presented before the font name
  then avoid looking for one afterwards.
* Fix \@fnsymbol; it was defined as a \protected macro, where in fact its internal text-or-math switch needed to be instead.
* No longer lowercase fontnames internally; this fixes a bug with loading
  mixed-case ".fontspec" files.
* Fixed some documentation typos/inconsistencies related to recent changes.
  • v2.4a (2014/06/21)
* No longer load fixltx2e.sty -- this package should really be loaded before \documentclass.
* Avoid deprecated l3fp code.
* A couple of bugs introduced with v2.4 fixed.
  • v2.4 (2014/06/01)
* Significant change to the user interface: instead of `\setmainfont[features]{font}`, you now write `\setmainfont{font}[features]`.
  Backwards compatibility is of course preserved.
  The reason for this change is to improve the visual comprehension of the font loading syntax with large numbers of font features.
* Defaults for symbolic font families like this can now be specified with
* New `PunctuationSpace=WordSpace` and `PunctuationSpace=TwiceWordSpace` settings, intended for monospaced fonts; these force the space after a period to be exactly one or two spaces wide, respectively, which preserves character alignment across lines.
* The features above now allow changes to the default settings:
  * `Ligatures=TeX` is enabled by default with `\setmainfont` and `\setsansfont`.
  * `WordSpace={1,0,0}` and `PunctuationSpace=WordSpace` are now enabled by default for `\setmonofont` to produce better monospaced results.
  * (These can be adjusted by created your own `fontspec.cfg` file.)
* `SizeFeatures` can now be nested inside `ItalicFeatures` (etc.) and behaves correctly. This has been a very long overdue bug!
* New feature `NFSSFamily=ABC` to set the NFSS family of a font to “`ABC`”. Useful
  when other packages use the `\fontfamily{ABC}\selectfont` interface.
* New feature `FontFace = {series}{shape}{font}` allows a font face to be loaded with a specific NFSS font series and font shape.
  A more verbose syntax allows arbitrary font features as well (and this also plays nicely with `SizeFeatures`):
          FontFace = {b}{ui}{Font = myfont-bui.otf, <features>} ,
  The code above, for example, will allow a bold upright italic font to be selected using the standard NFSS interface: `\fontseries{b}\fontshape{ui}\selectfont`.
* `\defaultfontfeatures+` (note the `+`) can now be used to append to the default font feature set.
* Setting the `SmallCapsFont` using the `*`-replacement notation has been improved/fixed.
  • v2.3c (2013/05/20)
* Compatbility with luaotfload 2013/05/20 2.2c, support for older version
  • v2.3b (2013/05/12)
* Compatibility with new (and future) version of luaotfload
  • v2.3a (2013/03/16)
* Bug fix update to retain compatibility with new expl3
  • v2.3 (2013/02/25)
* Add support for per-font options in `\defaultfontfeatures`
* Add support for `<fontname>.fontspec` per-font configuration files
* Keep up-to-date with expl3 changes
  • v2.2b (2012/05/06) "TL2012 ver­sion"
* Fix error with AutoFakeSlant/Bold (#113) and when used with external fonts (#128)
* Add warning when using FakeBold in LuaLaTeX, where it's not supported
* Fix slshape misassignment introduced in v2.2
* Allow fontspec to be loaded before \documentclass
  (or rather fix the regression that broke this)
* Avoid using the calc package now that it's no longer loaded by expl3
* Allow multiple values to StylisticSet and Alternate font options
  • v2.2a (2011/09/14)
* Bug fix: improve backwards compatibility for packages that use old
  fontspec internals such as mathspec.
  • v2.2 (2011/09/13)
* Support alternate selections in CharacterVariant (cvxx in OpenType)
  using new syntax `[CharacterVariant=5:2]`.
* Add `fontspec`-compatible `\oldstylenums` and `\liningnums` commands.
* New programmer's function `\fontspec_set_fontface:NNnn` (for use when
  `\zf@basefont` might previously have been queried).
* Log file output is slightly tidier.
* Some old lingering bugs squashed:
  - Small caps font selection was broken in some cases.
    (Thanks Enrico Gregorio.)
  - Fonts loaded by filename with under-specified shapes threw an error
    (e.g., asking explicitly for bold but not italic).
    (Thanks Vafa Khalighi.)
* Documentation improvements largely due to Markus Böhning.
* Many internal changes, among which:
  - `xkeyval` package no longer used for option processing;
    `expl3`'s `l3keys` used instead.
    This allows `fontspec` to be loaded before `\documentclass`
    (thanks Heiko Oberdiek for reporting the issue)
    and fixes a potential conflict with the `preview` package
    (thanks again Vafa).
  - Internal names changed; avoid "\zf@basefont", "\zf@family", etc.
    from now on -- there are public interfaces now to get access to the
    same information
  - Update `expl3` support to latest CTAN version.
  • v2.1g (2011/08/02)
* No longer uses the binhex package, avoiding some name clashes with TIPA
  • v2.1f (2011/02/26)
* Finally add a real error message when a font cannot be found!
* Add "Letters=Random" feature.
* Fix bug in which "Unknown feature `'..." warnings
  were shown in the log file.
* Some small documentation improvements.
  • v2.1e (2010/11/17)
* Internal changes for luatexbase v0.3.
  • v2.1d (2010/11/07)
* Bug fix when \itdefault is "sl" rather than "it".
  E.g., when using the "slides" class.
* Minor internal changes, including merging some code from unicode-math.
  • v2.1c (2010/10/13)
* New documentation for defining custom kerning and ligatures
  when using LuaLaTeX.
* Fix bug when defining bold italic fonts by filename.
* Avoid infinite loop when the Latin script is requested for a font
  that does not contain it. TODO: a suitable fallback script should be
  chosen; right now we just ignore the script selection.
  • v2.1b (2010/09/29)
* Fix for bug introduced in the last release:
  small caps weren't being automatically selected correctly
  • v2.1a (2010/09/27)
* Fix for colours bug introduced in the last update
* Fix for for bad interaction with LuaLaTeX and fallback fonts
  (such as using \slshape when no slanted font specified)
* Behaviour/messaging improvement when scripts/languages are requested
  that do not exist in the font
* Fix bug with detecting font features/scripts in some cases with:
    - `\fontspec_if_feature:n(TF)`
    - `\fontspec_if_language:n(TF)`
    - `\fontspec_if_current_script:n(TF)`
    - `\fontspec_if_current_language:n(TF)`
* Some messages in the log file are improved
* Code for "visible space" fixed for LuaLaTeX use
* Lots of internal changes to bring the implementation closer
  to being "native expl3".
  • v2.1 (2010/09/19)
* Now load xunicode internally for consistent behaviour in
  XeLaTeX and LuaLaTeX.
* Font commands now include \fontencoding internally, easing their
  use together with legacy TeX fonts.
* Colour & Opacity now behave a little better.
* Nested emphasis with \emph now also occurs inside a "slanted" shape.
* Some compatibility commands/options added that were removed.
  in the transition to v2.
* Bug fix for a problem triggered after counters got too high.
  • v2.0c (2010/08/01) Bug fix and doc­u­men­ta­tion tune-up.
* Significant bug fix reported simultaneously by Enrico Gregorio and
  Don Hosek.
* Many documentation improvements and additions due to David Perry.
* Documentation typo thanks to John McChesney-Young
  • v2.0b (2010/07/14) Ac­tu­ally the fi­nal re­lease be­fore TeX Live 2010.
* Improved examples in the documentation, with fewer proprietary fonts
* All font examples are included as separate images on CTAN, so the
  manual can be compiled (with pdfLaTeX) by anyone, anywhere
* LuaLaTeX fixes for the StylisticSet and Annotation features
* New OpenType feature `CharacterVariant` now supported
* Minor change: `Ligatures=Historical` is now `Ligatures=Historic` for consistency
  • v2.0a (2010/07/11) Fi­nal re­lease be­fore TeX Live 2010.
* Bug fix for the Language setting being ignored
* Add programmer's command `\fontspec_glyph_if_exist:NnTF`
* Many documentation improvements, especially for LuaTeX features
  `FeatureFile=...` and `Numbers=Arabic`.
* Add `Parsi` and `Persian` synonyms for `Language=Farsi`


If you are run­ning TeX Live, you can get the lat­est ver­sion of this pack­age by run­ning

tlmgr install fontspec

If you wish to down­load the lat­est re­lease ver­sion from CTAN, get the pre-built TDS pack­age and ex­tract it into your lo­cal texmf tree:


If you wish to use the lat­est de­vel­op­ment ver­sion from Github, ei­ther use git to ob­tain the bleed­ing edge ver­sion with

git clone git://github.com/wspr/fontspec.git

or if you don't have git you can down­load it from


Hav­ing ob­tained the pack­age from Github, ex­tract the pack­age code by run­ning

tex fontspec.dtx

and then move the nec­es­sary files into your lo­cal texmf tree. The doc­u­men­ta­tion can be com­piled by run­ning

xelatex -shell-escape fontspec.dtx

Th­ese steps are au­to­mated in the Make­file; run

texlua build.lua install

to com­pile the doc­u­men­ta­tion and in­stall all nec­es­sary files in your lo­cal texmf tree. Depend­ing how your TeX dis­tri­bu­tion is con­fig­ured you may then need to up­date the file­name database with texhash.


Copy­right 2004–2016 Will Robert­son <wspr81@gmail.com> Copy­right 2009–2010 Khaled Hosny <khaled­hosny@eglug.org>

Distributable un­der the LaTeX Project Public Li­cense, ver­sion 1.3c or higher (your choice). The lat­est ver­sion of this li­cense is at: http://www.la­tex-project.org/lppl.txt

This work is "main­tained" (as per LPPL main­te­nance sta­tus) by Will Robert­son.

Down­load the con­tents of this pack­age in one zip archive (818.0k).

fontspec – Ad­vanced font se­lec­tion in XeLaTeX and Lua

Fontspec is a pack­age for XeLaTeX and Lua. It pro­vides an au­to­matic and uni­fied in­ter­face to fea­ture-rich AAT and OpenType fonts through the NFSS in run­ning on or Lua en­gines.

The pack­age re­quires the l3k­er­nel and xparse bun­dles from the 3 de­vel­op­ment team.

Home pagehttp://github.com/wspr/fontspec/
Ver­sion2.5a 2016-02-01
Li­censeThe Project Public Li­cense 1.3
Main­tainerWill Robert­son
TDS archivefontspec.tds.zip
Con­tained inTeX Live as fontspec
MiKTeX as fontspec
Topics , ma­te­rial sup­port­ing it, and pack­ages re­quir­ing it
font se­lec­tion schemes
Lua and pack­ages that re­quire it
Guest Book Sitemap Contact Contact Author