Fonts¶

To render a workbook to PDF, HTML or SVG, EPPlus needs to know exactly how the text will look: how wide each character is, where lines break, and which glyphs to draw. For this, EPPlus has its own built-in font engine, which reads font files directly and works the same way on Windows, Linux and macOS.

What the font engine does¶

• Reads fonts. TrueType and OpenType fonts (.ttf, .otf) and font collections (.ttc) are read from the operating system's font directories and from directories you specify.
• Shapes text. Characters are turned into positioned glyphs using the font's own layout rules, including kerning, ligatures, contextual substitutions and the placement of diacritical marks.
• Measures text. Text widths and line heights are calculated from the font's metrics, which is what line breaking and layout in the exports are based on.
• Falls back when something is missing. When a font is not installed, or lacks the characters for a writing system, EPPlus uses metric-compatible substitutes, per-script fallback fonts and the bundled fonts described below. See Font fallbacks.
• Embeds fonts in PDF files. Fonts are subsetted, so that only the glyphs actually used are included, and the embedding permissions declared by each font are respected.
• Adapts fonts for browsers. For the HTML and SVG exports, Office cloud fonts such as Aptos are replaced by fonts that browsers can use.

Bundled fonts¶

Three fonts are included in EPPlus and are always available:

Other fonts, including fonts for writing systems such as Chinese, Japanese, Korean and Arabic, are not bundled and must be installed or supplied through a font directory.

In this section¶

• Configure fonts: where fonts are loaded from, fallback chains, font embedding in PDF files, and custom font resolution.
• Font fallbacks: how missing fonts and characters are handled, with the built-in fallback chains and how to find out which fonts were used.

Fonts on servers and in containers¶

The most common source of unexpected output is a server or container that lacks the fonts used in the workbooks. The export still succeeds, but text may be drawn in a substitute font, with different widths and line breaks, or with missing-glyph boxes for writing systems that no available font covers.

To get the intended result, either install the fonts the workbooks use, or ship them with your application and add their directory with FontDirectories. If you can't distribute the original fonts, installing the metric-compatible open fonts Carlito, Caladea and the Liberation family gives substitutes with the same widths for the most common Office fonts.