Contact Us


Initiative B@bel

WSI Guidelines


















Type Design


Design Tools



Font Downloads










Font FAQ



Computers & Writing Systems


You are here: Rendering > Resources
Short URL: https://scripts.sil.org/xetex_faq


Jonathan Kew, 2004-05-20

Where to go for help

Note: SIL International no longer manages XeTeX development. Please refer to the following paragraphs to find excellent sources of help.

XeTeX Home  http://xetex.sourceforge.net/

For questions or discussion about installing or using XeTeX and related packages, please go to the  XeTeX mailing list hosted by the TeX Users Group, where experienced users and developers are likely to be able to help.

For bug reports about the XeTeX software itself, or specific feature requests (rather than general discussion), there is an  issue tracker hosted at SourceForge.

The comment form on this page is available for general comments about the software or the web pages themselves (yes, I know they need updating!), but please do not expect technical support through this channel. You are much more likely to get useful responses on the  mailing list.

Update — September 2013

The latest release of XeTeX is version 0.9999.3, which is included in  TeX Live 2013. XeTeX is a standard component of the complete  TeX Live distribution. This includes all major TeX-related programs and a huge range of additional fonts, macro packages, and utilities, with ready-to-use binaries for around 15 computer platforms including Mac OS X (PPC and x86), Windows, and various Linux and Unix-like systems on a range of CPU architectures.

The TeX Users Group hosts a  XeTeX mailing list where interested users are welcome to discuss bugs, workarounds, wishes, etc.; while no commitments can be made as to future development, all feedback is greatly appreciated.

This page attempts to provide answers to some commonly-asked questions about XeTeX.


Front-ends and macro packages

Characters and fonts


Another possible source of help is the  XeTeX mailing list hosted by the TeX Users Group and maintained by Ross Moore. (Thanks, Ross!)

Remember that XeTeX is a work in progress; documentation is sorely lacking at this point. If you have successfully installed XeTeX, some features are documented (perhaps only by example!) in the sample files available from the Downloads page.

Question: Can XeTeX be used with a TeX system installed by Fink (or DarwinPorts, or TeXlive, or ...), instead of i-Installer?

Answer: Yes, but for now you may have to install manually rather than using the installer package. This is a procedure for those who are comfortable with the Terminal and understand their TeX installation. First, copy the Archive.pax.gz file from the installer package into a convenient location such as your home directory (use Show Package Contents in the Finder to look inside the package). Then, in Terminal, execute:

gunzip Archive.pax
pax -r < Archive.pax

This will unpack the archive into two directories, bin and share, whose contents should be merged into your existing TeX hierarchy.

In addition, you'll need to add two lines:
xetex           xetex           -               *xetex.ini
xelatex         xetex           language.dat    *xelatex.ini

to the fmtutil.cnf file.

(You should be able to use kpsewhich to locate these configuration files.)

For more detailed notes, see Installing XeTeX with Fink's teTeX.

▵ Top of page

Question: XeTeX is installed, but there's no xelatex.fmt format so I can't use it with LaTeX files. And fmtutil can't seem to build this format. What's wrong?

Answer: The xelatex.fmt file, along with the "plain" xetex.fmt, is supposed to be created and installed by the configuration script. To see what went wrong, you can re-run the installer and review the output of the scripts (use Show Log in the Apple Installer, or View Subprocess Output in i-Installer).

One reason the creation of xelatex.fmt may fail is related to hyphenation files and language settings. XeTeX reads all input files as Unicode text. However, the standard hyphenation files for many languages use encodings such as the TeX-Latin1 (Cork) encoding or various others. Such files, if they include literal characters in the range above 127, will almost certainly cause XeTeX to fail, with an "invalid character" error. This problem has been reported with Russian and Hungarian pattern files, and probably applies to others as well.

The correct solution to this is to create true Unicode versions of all such input files; then the patterns can be loaded and will work as intended with Unicode text. (Note that although simply using hex sequences ^^xx to represent the 8-bit character codes should allow XeTeX to read the files, the resulting hyphenation patterns will not be right for true Unicode text, only for text that uses that same legacy encoding.)

A workaround to allow xelatex.fmt to be created is to skip the loading of hyphenation patterns for whichever languages are causing the problem, by modifying the language.dat file, usually found somewhere like texmf/tex/generic/config/.

▵ Top of page

Question: Can I use  iTeXMac as a front end for XeTeX, rather than TeXShop?

Answer: Yes, if you're comfortable with setting it up. I mention TeXShop because that's what I use, and because it is simple for a new user to configure TeXShop to work with XeTeX. But it's certainly possible to use iTeXMac instead, and I believe it offers more options for customization and extension.

A separate page of notes on configuring iTeXMac is now available. In brief, to configure iTeXMac to use Unicode (UTF-8) as the encoding for text files, as expected by XeTeX, you can install the Encodings.plist file provided in iTeXMac Support/Font Encodings Support into ~/Library/Application Support/iTeXMac/General. Then edit this file through Format/String Encodings/Customize… to add Unicode (UTF-8) to the list of available encodings.

Then, to use XeTeX to typeset documents, you should create a new iTeXMac project, specifying xetex (or xelatex, as appropriate) in the compile script. It should be simple to do this by duplicating and modifying the pdftex.pTeXMac and pdflatex.pTeXMac projects, for example.

▵ Top of page

Question: Can I use XeTeX with the ConTeXt package?

Answer: Yes, the latest  ConTeXt release (2004.11.23 at the time of writing) includes support for the XeTeX engine.

Some notes on installation and getting started, kindly provided by Adam Lindsay, are available on the  ConTeXt Wiki.

▵ Top of page

Question: Why doesn't the usual TeX code --- produce a long dash when I use Unicode fonts in XeTeX?

Answer: The interpretation of -- as an en-dash, --- as em-dash, and a few other conventions (e.g., opening and closing quote marks) is a feature of the fonts typically used with TeX, not of the program itself or the macro packages. These characters are implemented as ligatures in the Computer Modern fonts, and this pattern has been followed by the typical setups for other fonts such as Times, etc., when used with TeX.

However, standard Unicode-compliant fonts do not include ligatures for these sequences, as the normal expectation is that the actual Unicode characters will be used in the source text.

For compatibility with input files that use the traditional TeX conventions, you can load such fonts in XeTeX with the "tex-text" font mapping, which simulates the behavior of typical TeX fonts by replacing sequences such as -- with en-dash, etc.

Thus, in Plain TeX terms, you can say things like:

    fontx="Times Roman:mapping=tex-text" at 12pt 

to get a font that treats --, etc., as TeX users are accustomed to. If you're loading fonts via the fontspec package in LaTeX, you can say:


in order to automatically apply this mapping to the subsequent fonts you load.

▵ Top of page

Question: The Plain TeX commands for accents and European characters such as æ and ß don't work in XeTeX — why?

Answer: Commands such as ae (æ) or ' (acute accent) are defined as macros in plain.tex using character codes that are specific to the custom 8-bit encoding of the Computer Modern fonts; for example:

def'#1{{accent19 #1}}

Therefore, they will not work with Unicode fonts in XeTeX, as the required characters are not accessed by the same codes.

In LaTeX, the font selection mechanism, fontenc package, etc., provide support for using different font encodings, redefining these commands as needed to match the character encoding of the current font. For XeLaTeX, the xunicode package provides Unicode-compliant versions of these commands, so that existing documents can work with Unicode fonts.

For plain XeTeX, however, there is no built-in mechanism to handle the encoding differences between CM and Unicode fonts. You can redefine the plain TeX macros to work with Unicode; for example, acute and æ could be defined as:

def'#1{{accent"00B4 #1}}

(and similarly for other characters). These definitions are not provided by default in the xetex.fmt format file, however, as they will not work with the standard Computer Modern fonts, only with Unicode fonts. To support such macros in documents that mix non-Unicode and Unicode fonts, more complex font-switching macros (such as the LaTeX font selection scheme) are required.

▵ Top of page

Question: Does XeTeX work with OpenType fonts?

Answer: Yes (at least somewhat)! See the OpenType examples in the Sample Files archive. Note that the appropriate OpenType fonts (not supplied with XeTeX) will be needed to typeset these samples.

The OpenType support is a preliminary implementation and I hope to refine it in future versions. If Apple would build in support OpenType layout features at the ATSUI API level, it would be far preferable, and would enable such fonts to work in other applications as well, not only within the XeTeX typesetting engine.

I would encourage people to provide feedback to Apple, requesting full support of OpenType layout features in the Mac OS X text APIs.

▵ Top of page

Question: Why do I get warnings about Type1 fonts when I run XeTeX?

Answer: Whenever the XeTeX document uses a Computer Modern font or other legacy TeX font, rather than TrueType or OpenType fonts installed in Mac OS X, the program generates the message:

WARNING: Type1 font data returned by OFAStreamPSDownload isn't in the correct format
required by the Adobe Type 1 Font Format specification.

This message appears in the Terminal window (if running XeTeX from the command line) or in the system log file on Mac OS X 10.4, but not on earlier versions. The exact cause is currently not known. It appears to be harmless; the resulting PDF files still display and print correctly.

▵ Top of page

Question: I get an illegal font name error trying to use an AAT (or OpenType) font; what's wrong?

Answer: This error comes from the mktextfm tool when it is asked to build a .tfm file for a font, but the font name includes characters such as space. Generally, this means that the name you specified in the font command does not exactly match the name of the font installed in Mac OS X; therefore, xetex didn't find the installed font, and tried to use a .tfm instead.

To check the name of a font, look in Font Book to see what name is displayed under the sample text, when you select the font family and face you're trying to use. For example, the Regular face of Times is called "Times Roman", whereas the Regular face of Palatino is simply "Palatino". So asking for "Palatino Roman" will lead to an illegal font name error.

▵ Top of page

Question: Why don't the samples with Computer Modern fonts work?

Answer: Assuming XeTeX is installed and most things are working, this probably means that the xdv2pdf tool that actually generates PDF output can't find the Computer Modern fonts. Instead, you get messages such as:

*** font cmr10 (CMR10: file 'cmr10') not found

and the resulting PDF is blank.

The most likely cause is that the appropriate font map entries are not present in the psfonts.map file that xdv2pdf uses to locate PostScript fonts corresponding to .tfm files used in TeX. The updmap tool can be used to enable the necessary .map files.

Answer: If you run xetex from the command line with the -no-pdf option, it will create an .xdv (extended DVI) file. You can then run the xdv2pdf tool to convert this to PDF format, using the -v (verbose) flag, which causes it to print messages indicating what fonts and encoding files are loaded. If the right files are not being found, you can use the -d flag with a numeric argument to set debugging options for the kpathsearch library, as with other TeX tools. Thus,

xetex -no-pdf myfile.tex
xdv2pdf -v myfile.xdv

will simply report mapping files and fonts loaded, and

xdv2pdf -d -1 myfile.xdv

will give extensive tracing of the file search process. This may help in diagnosing search path errors in the configuration.

▵ Top of page

Question: With XeTeX, how can I make a PDF file with Chinese/Japanese/Korean/Cyrillic/etc. bookmarks?

Answer: Sorry, with the current hyperref support in the xdv2pdf driver (as of version 0.99b), there is no way to put non-Latin characters into PDF bookmarks. This should change in a future release, when I hope to provide an alternative method of PDF generation.

▵ Top of page

Question: Help! XeTeX seems to enter a loop, endlessly printing [][][][][].... to the console. What can I do?

Answer: This is a bug, present in all versions of XeTeX up to 0.88, that appears when the extra_mem_bot value in the TeX configuration file texmf.cnf is non-zero. This value has often been set for ConTeXt configurations, and in recent releases of the gwTeX package it is non-zero by default.


As of XeTeX version 0.9, this bug should no longer occur; therefore, updating to the latest available release is the recommended course of action.

To work around the problem (for versions prior to 0.9), edit the configuration file (typically found at /usr/local/teTeX/share/texmf/web2c/texmf.cnf; this will be different for Fink users). This will typically require a sudo command in the Terminal, or similar authorization. Find the "Memory" section, and add entries:

extra_mem_bot.xetex = 0
extra_mem_bot.xelatex = 0

ConTeXt users should also change the entry for that format:

extra_mem_bot.context = 0

If this leads to out-of-memory problems, increase the main_memory setting; but in this case, the format files need to be regenerated for the new value to take effect.

▵ Top of page

Question: Why do I get an Undefined control sequence error when I try to typeset a file that uses the picfile or pdffile command?

Answer: These names are no longer supported. These command names existed in early versions of XeTeX, but were changed to XeTeXpicfile and XeTeXpdffile respectively in release 0.5. This change was made to reduce the likelihood of name conflicts with existing macro sets. You can add the lines:


at the beginning of existing files that use the old names, if you don't want to change all occurrences.

▵ Top of page

Note: If you want to add a response to this article, you need to enable cookies in your browser, and then restart your browser.

Note: the opinions expressed in submitted contributions below do not necessarily reflect the opinions of our website.

"", Sun, Sep 28, 2008 13:08 (EDT)

macports and fink

xetex is now available through macports (as part as the "texlive" package) and through fink (as package "xetex").

Note: If you want to add a response to this article, you need to enable cookies in your browser, and then restart your browser.

© 2003-2022 SIL International, all rights reserved, unless otherwise noted elsewhere on this page.
Provided by SIL's Writing Systems Technology team (formerly known as NRSI). Read our Privacy Policy. Contact us here.