> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/questions-and-answers/58-i-have-a-custom-font-i-d-like-to-load-to-my-document.-how-can-i-do-this.md).

# I have a custom font I'd like to load to my document. How can I do this?

## Introduction

This article shows how to install custom fonts for typesetting your document’s text—it does not address fonts for typesetting mathematics. By “custom font”, we mean one unavailable on Overleaf’s servers, including commercial fonts that require a license or free-to-use fonts not distributed with TeX Live or included in our Linux installation.

* **Note**: This article addresses mainstream font technologies but does not discuss specialist TeX-based solutions such as [Metafont](https://en.wikipedia.org/wiki/Metafont) and [virtual fonts](https://texfaq.org/FAQ-virtualfonts).

## Where do I start?

LaTeX-based typesetting solutions operate in the context of legacy. Over four decades, the development of LaTeX compilers and font formats has produced an ecosystem comprising a blend of older and new technologies. As a result, the actual process of installing and configuring custom fonts for use with LaTeX depends on these two factors:

1. The type (format) of any font(s) you want to install:

* legacy [PostScript Type 1](https://en.wikipedia.org/wiki/PostScript_fonts#Type_1) or [TrueType](https://en.wikipedia.org/wiki/TrueType) fonts, or
* modern [OpenType](https://en.wikipedia.org/wiki/OpenType) fonts.

3. Which LaTeX compiler is used to compile your Overleaf project(s):
   * pdfLaTeX, or
   * XeLaTeX or LuaLaTeX

Jump to the section covering your preferred compiler:

* [Using custom fonts with pdfLaTeX](#using-custom-fonts-with-pdflatex)
* [Using custom fonts with XeLaTeX and LuaLaTeX](#using-custom-fonts-with-xelatex-and-lualatex)

## Using custom fonts with pdfLaTeX

Here is a summary of what you’ll need to do—depending on the complexity of your custom font setup:

1. For each font file (`.ttf`, `.otf` or `.pfb`), you will need to have (or generate!) a suitable TeX font metric (`.tfm`) and, perhaps, an encoding file (`.enc`).
2. pdfLaTeX must know how to embed document fonts into the final PDF file. To do that, it reads a font map file (`pdftex.map`), which you’ll need to update with details of your custom font. On Overleaf, you do that using one of these commands:

* `\pdfmapfile{...}`
* `\pdfmapline{...}`

4. You will need a font description (`.fd`) file which tells LaTeX how to use the new font files.

These are the main file types you will require:

* **`.tfm`** (TeX font metric): these compact binary files do not contain any data describing the visual appearance of character shapes, only character dimensions and font “metadata” that TeX engines can use to perform their core typesetting tasks. TeX font metrics for math fonts contain additional data not required by text-only fonts; in particular, they have several “spacing” parameters used for typesetting maths.
* **`.fd`** (font description): these files contain LaTeX commands required to configure and prepare your font for use with LaTeX. Commands permitted within `.fd` files, and the `.fd` file-naming convention, are described in the document [LaTeX2ε font selection](https://texdoc.org/serve/fntguide/1).
* **`.map`** (font map): map files link the name of TeX font metrics files with the physical font file containing data required to draw character shapes (glyphs). Each font known to pdfTeX is described on a single line of the map file, using a well-defined syntax. For full details, see Section 5 of [The pdfTeX user manual](http://mirrors.ctan.org/systems/doc/pdftex/manual/pdftex-a.pdf).
* **`.enc`** (encoding): if required, this file type defines the mapping between character codes within your LaTeX text and the corresponding character shapes (glyphs) contained within the font file.

### Custom TrueType font example

The Overleaf Galley contains a project that [demonstrates installing a custom TrueType font](https://www.overleaf.com/latex/examples/example-using-a-custom-truetype-font/yndxyzgbhpjv)—a PostScript Type 1 font would use a similar setup. It compiles with pdfLaTeX, XeLaTeX and LuaLaTeX and produces the following output:

![Image showing Overleaf typesetting using a custom font](/files/gwtLufl1RubECfFODsBJ)

#### Notes on the example project

* It uses the following `\pdfmapline` command:

```latex
\pdfmapline{+delphine < Delphine.ttf <T1-WGL4.enc}
```

which links a TeX font metric file called `delphine` to the physical font file called `Delphine.ttf`.

* The first `<` character instructs pdfTeX to subset the TrueType font; i.e., *partially* embed this font into the final PDF file. Subsetting a font produces smaller PDF files because they only contain the character-shape data required to display characters present in the document.
* The second `<` character precedes the name of an encoding vector file, `T1-WGL4.enc`, used to map from the character codes in your text to character-shape data (glyphs) within the font file—character-shape data is required to render (draw) the character.
* LuaLaTeX requires an extra configuration step because `\pdfmapline` generates an **Undefined control sequence** error due to changes in LuaTeX’s handling of certain backend commands—Section 3 of the [LuaTeX Reference Manual](http://mirrors.ctan.org/systems/doc/luatex/luatex.pdf). The `\ifLuaTeX` command, provided by the `iftex` package, is used to test for LuaTeX; if detected, `\pdfmapline` is defined:

```latex
\ifLuaTeX
\protected\def\pdfmapline {\pdfextension mapline }
\fi
```

### Using multiple fonts or commercial fonts

To manage files provided by commercial font vendors and collections of free-to-use fonts, you can create folders in your Overleaf project to organize font files according to their type (`.tfm`, `.pfb`, `.ttf` etc.). A good model for naming and organizing your folders is the [TeX Directory Structure (TDS)](https://www.tug.org/tds/tds.pdf), which was designed as a best practice “blueprint” for managing a collection of TeX-related files.

With the project folders in place, you next need to create a so-called [`latexmcrc` file](/latex/in-depth-articles/28-how-to-use-latexmkrc-with-overleaf.md) containing instructions telling the LaTeX compiler to search for files in those folders. By default, the compilers do not know those folders exist and will not find the files they contain.

#### Overleaf project example

The Overleaf Gallery example [Using Folders to Manage Custom Font Files](https://www.overleaf.com/latex/templates/example-using-folders-to-manage-custom-font-files/qvqgnpjxvqzd) uses folders and a `latexmkrc` file to install a custom TrueType font. It contains a folder structure shown in this image:

![Organizing project folders on Overleaf](/files/FYOwaOYZuodPAdpMV9mV)

and a `latexmkrc` file containing the following lines, which set runtime [environment variables](https://en.wikipedia.org/wiki/Environment_variable) telling the LaTeX compiler to look for files in our project folders:

```perl
$ENV{'TEXINPUTS'}='myfonts/tex//:' . $ENV{'TEXINPUTS'};
$ENV{'T1FONTS'}='myfonts/fonts/type1//:' . $ENV{'T1FONTS'};
$ENV{'AFMFONTS'}='myfonts/fonts/afm//:' . $ENV{'AFMFONTS'};
$ENV{'TEXFONTMAPS'}='myfonts/fonts/map//:' . $ENV{'TEXFONTMAPS'};
$ENV{'TFMFONTS'}='myfonts/fonts/tfm//:' . $ENV{'TFMFONTS'};
$ENV{'TTFONTS'}='myfonts/fonts/ttf//:' . $ENV{'TTFONTS'};
$ENV{'VFFONTS'}='myfonts/fonts/vf//:' . $ENV{'VFFONTS'};
$ENV{'ENCFONTS'}='myfonts/fonts/enc//:' . $ENV{'ENCFONTS'};
```

If you’re wondering which files typically go into which folder, have a look at [this article](/latex/in-depth-articles/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md#table-listing-kpathsea-config-variables).

## Using custom fonts with XeLaTeX and LuaLaTeX

### Using PostScript Type 1 fonts

To use legacy PostScript Type 1 fonts with XeLaTeX and LuaLaTeX, you can follow the [guidelines for pdfLaTeX](#using-custom-fonts-with-pdflatex), so we won’t repeat those details here.

### Using OpenType fonts

XeLaTeX and LuaLaTeX provide extensive support for advanced typesetting using OpenType fonts—TrueType and PostScript varieties—because their underlying TeX engines, XeTeX and LuaHBTeX, have native (built-in) capabilities to process OpenType font technologies, which pdfTeX does not.

* **Note**: LuaLaTeX, via its underlying TeX engine (LuaHBTeX), has the most sophisticated font-handling capabilities of all TeX engines; however, discussing these is beyond the scope of this article—for more information, see sections 6 and 12 of the [LuaTeX Reference Manual](https://ctan.org/pkg/luatex?lang=en).

To use OpenType fonts with XeLaTeX and LuaLaTeX, you need to load [`fontspec`](https://ctan.org/pkg/fontspec?lang=en), a powerful and feature-rich package which provides an interface to the advanced typesetting capabilities of OpenType fonts.

* **Note**: You do not need to use `\usepackage[T1]{fontenc}` (or `\usepackage[utf8]{inputenc}`) when using OpenType fonts with XeLaTeX or LuaLaTeX.

### Example: introducing fontspec

The process is straightforward because no font installation is required—no need for `.tfm`, `enc` or `.map` files and writing font definitions (`.fd`) is consigned to history! It is as simple as this:

1. Add the following line to your document preamble:

```latex
\usepackage{fontspec}
```

3. Select the file upload icon (![UploadIcon.png](/files/DJNemicsNYqc4Rzryh9e)), located above the file list.
4. Drag and drop the font(s) onto the upload modal, or select them from your computer, to add the font(s) to your Overleaf project.
5. Use one of the `fontspec` package `\set*xxx*font` commands to configure and activate the font(s).

The excellent `fontspec` package documentation provides a wealth of examples you can explore, so here, we'll keep it straightforward to help you get started. For example, suppose you upload a font file called `CrimsonText-Regular.ttf`; after loading `fontspec` you can set the main document text font by writing

```latex
\setmainfont{CrimsonText-Regular.ttf}
```

You can also write syntax such as

```latex
\setmainfont{CrimsonText}[
Extension = .ttf,
UprightFont = *-Regular,
...]
```

You can also declare a new font family to use in arbitrary situations:

```latex
\newfontfamily{\crimson}{CrimsonText}
[Extension = .ttf, UprightFont = *-Regular, ...]
{\crimson This text uses the CrimsonText font}
```

#### Resources

* The [`fontspec` package documentation](http://mirrors.ctan.org/macros/unicodetex/latex/fontspec/fontspec.pdf) is a must-read—it not only provides numerous helpful examples but also contains a lot of useful background information on OpenType fonts.
* The Overleaf help page on [XeLaTeX](/latex/fonts/03-xelatex.md) contains a [detailed example](/latex/fonts/03-xelatex.md#using-fonts-not-installed-on-overleaf27s-servers-google-fonts-example) showing how to download OpenType fonts from Google and configure them with `fontspec`.

**Sample projects**

The Overleaf Galley has example projects that demonstrate using OpenType fonts with XeLaTeX or LuaLaTeX—you can open these and switch the compiler between LuaLaTeX and XeLaTeX:

* [Using Google fonts with XeLaTeX](https://www.overleaf.com/latex/templates/using-google-fonts-with-xelatex/xxkpcgfttjvd)
* [Using the STIX2 OpenType fonts with LuaLaTeX or XeLaTeX](https://www.overleaf.com/latex/templates/using-the-stix2-opentype-fonts-with-lualatex-or-xelatex/hdfvhzqmhnpx)

The next graphic combines the output produced by these projects:

![Sample Overleaf projects using Opentype fonts](/files/kCfiETVyQ7eJ1z139IZd)

## Font and LaTeX compiler basics

### Font file extensions

The table below lists file extensions used to indicate different types (formats) of font files:

|                                                                                                                   |                  |
| ----------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Font type**                                                                                                     | **Extention**    |
| [PostScript Type 1](https://en.wikipedia.org/wiki/PostScript_fonts#Type_1)$$\displaystyle{}^{\mathbf\*}$$         | `.pfb`           |
| [TrueType](https://en.wikipedia.org/wiki/TrueType)                                                                | `.ttf`           |
| [TrueType Collections](https://learn.microsoft.com/en-us/typography/opentype/otspec150/otff#truetype-collections) | `.ttc`           |
| [OpenType](https://learn.microsoft.com/en-us/typography/opentype/)                                                | `.otf` or `.ttf` |

$$\displaystyle{}^{\mathbf\*}$$ In January 2023, all of Adobe’s authoring applications [ceased support of the legacy Type 1 font format](https://helpx.adobe.com/uk/fonts/kb/postscript-type-1-fonts-end-of-support.html).

OpenType fonts exist in two “varieties”, often called “flavours”: PostScript-flavour and TrueType-flavour, names which reflect the data and mechanism(s) used to represent the character shapes (glyphs) they contain. That is why OpenType fonts have two file extensions: `.otf` or `.ttf` which, by *convention*, imply:

* `*filename*.otf` is a PostScript-flavour OpenType font
* `*filename*.ttf` is a TrueType-flavour OpenType font

For example, pdfTeX assumes the extension `.otf` indicates a PostScript-flavour OpenType font.

* **Note**: the `.ttc` extension is used only for TrueType Font Collections.

### About the .ttf file extension

Given a font file with a `.ttf` extension, it could be either:

* an older (non-OpenType) TrueType font, or
* an OpenType font containing TrueType data plus the extra features provided by OpenType.

Determining whether a given `.ttf` font file is OpenType or plain TrueType can be tricky, requiring applications to probe/investigate the font’s internal data structures. For further details, see [this discussion (thread)](https://typedrawers.com/discussion/2945/determine-whether-a-font-file-is-opentype-format-or-truetype-format) or this [Microsoft article](https://learn.microsoft.com/en-us/typography/opentype/#why-is-my-opentype-font-listed-as-a-truetype-font-by-my-application).

### Font formats and LaTeX compilers

The following table summarizes the (mainstream) font formats supported by three LaTeX compilers (strictly speaking, supported by the underlying TeX engines):

|              |                         |                                                        |                                                        |                                            |
| ------------ | ----------------------- | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------ |
| **Compiler** | **PostScript (Type 1)** | **TrueType (plain**$$\displaystyle{}^{\mathbf†}$$**)** | **OpenType (TrueType)**$$\displaystyle{}^{\mathbf\*}$$ | **OpenType (PostScript)**                  |
| pdfLaTeX     | Yes                     | Yes                                                    | Limited$$\displaystyle{}^{\mathbf{\*\*}}$$             | Limited$$\displaystyle{}^{\mathbf{\*\*}}$$ |
| XeLaTeX      | Yes                     | Yes                                                    | Yes                                                    | Yes                                        |
| LuaLaTeX     | Yes                     | Yes                                                    | Yes                                                    | Yes                                        |

$$\displaystyle{}^{\mathbf†}$$By “plain”, we mean a TrueType font that does not contain the additional data (tables) defined by the OpenType specification, thus lacks the more advanced typesetting features of TrueType-flavour OpenType fonts.

$$\displaystyle{}^{\mathbf\*}$$pdfTeX provides limited support for [TrueType Collections](https://learn.microsoft.com/en-us/typography/opentype/otspec150/otff#truetype-collections) (extension `.ttc`)—it will only read data for the first font contained in the collection.

$$\displaystyle{}^{\mathbf{\*\*}}$$pdfTeX’s “Limited” OpenType support means:

* it does not support the advanced typesetting features contained in OpenType fonts;
* it will subset TrueType-flavour OpenType fonts but not PostScript-flavour OpenType fonts which must be fully embedded. The absence of font subsetting produces larger PDF files and raises licensing problems with commercial fonts, which usually forbid full embedding;
* it cannot utilize more than 256 characters per font, whereas individual OpenType fonts support tens of thousands;
* it requires the production of TeX font metrics and other ancillary files (required by LaTeX)—processes that are outside the scope of this article (see [Further reading](#further-reading) for links to descriptions of those processes).

## Further reading

* [How OpenType Works](https://simoncozens.github.io/fonts-and-layout/opentype.html) (by Simon Cozens).
* [Determine whether a font file is an OpenType format or TrueType format](https://typedrawers.com/discussion/2945/determine-whether-a-font-file-is-opentype-format-or-truetype-format)—a discussion of the difficulty determining whether a given `.ttf` is plain TrueType or TrueType-flavour OpenType.
* [A closer look at TrueType fonts and pdfTeX](https://tug.org/TUGboat/tb30-1/tb94thanh.pdf)—a TUGboat paper written by [Hàn Thế Thành](https://tug.org/interviews/thanh.html), the creator of [pdfTeX](https://www.tug.org/applications/pdftex/).
* [A Directory Structure for TeX Files](https://tug.org/tds/tds.html), a standard folder/directory hierarchy for organizing TeX-related files.
* [The installation and use of OpenType fonts in LaTeX](https://www.tug.org/TUGboat/tb27-2/tb87owens.pdf)—a TUGboat paper explaining how to prepare OpenType fonts for use with pdfLaTeX.
* [How do I use TrueType Fonts with PdfTeX using otftotfm?](https://tex.stackexchange.com/questions/52819/how-do-i-use-truetype-fonts-with-pdftex-using-otftotfm/52902#52902)—a tex.stackexchange thread containing a detailed example.

### A note on the “font wars”...

The 1980s and 1990s saw the so-called “font wars” as two competing font formats, PostScript Type 1 (from Adobe) and TrueType (created by Apple, licensed to Microsoft), battled for supremacy—to win the hearts and minds of all users, especially designers and typographers. Eventually, the [OpenType font format](https://learn.microsoft.com/en-us/typography/opentype) emerged (in 1997) as a hybrid solution, encompassing and extending Adobe and Apple’s font technologies. OpenType builds on the original TrueType file format to enable advanced typesetting capabilities and better Unicode support through fonts containing over 65,000 character shapes (glyphs).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/questions-and-answers/58-i-have-a-custom-font-i-d-like-to-load-to-my-document.-how-can-i-do-this.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.