Font configuration

From ArchWiki
Jump to navigation Jump to search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki: Information on adding fonts and font recommendations Template:Article summary wiki: Fonts specific to Sun's Java machine Template:Article summary wiki: Adding Microsoft fonts and mimicking Windows' font settings Template:Article summary end

Font paths

For fonts to be known to applications, they must be cataloged for easy and quick access. Fontconfig is a library designed to provide a list of available fonts to applications, and also for configuration for how fonts get rendered. Though fontconfig is the standard in today's Linux, some applications still rely on the original method of font categorization: the Xorg server configuration.


Fontconfig gathers all its configurations in a central file (Template:Filename). Fontconfig-aware applications source this file to know available fonts and how they get rendered. This file is a conglomeration of rules from the various fontconfig configurations (the global configuration (Template:Filename), the configured presets in Template:Filename, and the user configuration file (Template:Filename).

The font paths initially known to fontconfig are: Template:Filename and Template:Filename (of which fontconfig will scan recursively). For ease of organization and installation, it is recommended to use these font paths when installing new fonts.

To see a list of known fontconfig fonts in an easy to read format:

$ fc-list | sed 's,:.*,,' | sort -u


Check for Xorg's known font paths by reviewing its log:

$ grep /fonts /var/log/Xorg.0.log

Keep in mind that Xorg does not search recursively through the Template:Filename directory like fontconfig does. To add a path, the full path must be used:

Section "Files"
    FontPath     "/usr/share/fonts/example-font-directory"

To see a list of known Xorg fonts use Template:Codeline.

Fontconfig configuration

The font rendering packages on Arch Linux includes support for freetype2 with the bytecode interpreter (BCI) enabled. However, defining your own font configuration may at times be necessary. Consider using patched packages for better font rendering, especially with an LCD monitor.

Configuration can be done either per-user through Template:Filename, or globally with Template:Filename. The settings in the per-user configuration have precedence over the global configuration. Both these files use the same syntax. Remember not to edit the Template:Filename file; it is a temporary file and shouldn't be edited since it's replaced during fontconfig updates.

There are already a number of configured presets in the directory Template:Filename. These presets can be linked to both per-user and globally for quicker configuration. Take note that these presets will override matching settings in their respective configuration files.

For example, to enable sub-pixel RGB rendering globally:

# cd /etc/fonts/conf.d
# ln -s ../conf.avail/10-sub-pixel-rgb.conf

To do the same but instead for a per-user configuration:

$ mkdir ~/.fonts.conf.d
$ ln -s /etc/fonts/conf.avail/10-sub-pixel-rgb.conf ~/.fonts.conf.d
Note: For some desktop environments (such as Gnome and KDE) using the Font Control Panel will automatically create or overwrite the user font configuration file. For these desktop environments, it is best to match your already defined font configurations to get the expected behavior.

The configuration files will need informational headers before settings can be entered:

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">

  <!-- settings go here -->


To avoid repetition, the rest of the configuration examples in this article will omit these tags.


Font rasterization converts vector font data to bitmap data so that it can be displayed. The result will appear jagged due to aliasing, so anti-aliasing is enabled by default to increase the apparent resolution of font edges.

  <match target="font">
    <edit name="antialias" mode="assign">


Font hinting (also known as instructing) is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid, such as the pixel grid in a display. Fonts will not line up correctly without hinting until displays have 300 DPI or greater. Two types of hinting are available.

Byte-Code Interpreter (BCI)

Using normal hinting, TrueType hinting instructions in the font are interpreted by freetype's Byte-Code Interpreter. This works best for fonts with good hinting instructions.

To enable normal hinting:

  <match target="font">
    <edit name="hinting" mode="assign">


Auto-discovery for hinting. This looks worse than normal hinting for fonts with good instructions, but better for those with poor or no instructions.

To enable auto-hinting:

  <match target="font">
    <edit name="autohint" mode="assign">
Note: Do not use the autohinter with subpixel rendering. The two are not designed to work together. The Infinality package fixes this.

Hint style

Hint style is the amount of influence the hinting mode has. Hinting can be set to: Template:Codeline, Template:Codeline, Template:Codeline and Template:Codeline. With BCI hinting, hintfull should work best for most fonts. With the autohinter, hintslight is recommended.

  <match target="font">
    <edit name="hintstyle" mode="assign">

Subpixel rendering

Subpixel rendering effectively triples the horizontal (or vertical) resolution for fonts by making use of subpixels.

Most monitors manufactured today use the Red, Green, Blue (RGB) specification. Fontconfig will need to know your monitor type to be able to display your fonts correctly.

RGB (most common), BGR, V-RGB (vertical), or V-BGR

To enable subpixel rendering:

  <match target="font">
    <edit name="rgba" mode="assign">

If you notice unusual colors around font's borders, discover you monitor type here.

Note: Do not use the autohinter with subpixel rendering. The two are not designed to work together. The Infinality package fixes this.

LCD filter

When using subpixel rendering, you should enable the lcd filter.

The Template:Codeline filter will work for most users. Other filters are available that can be used in special situations: Template:Codeline; a lighter filter ideal for fonts that look too bold or fuzzy, Template:Codeline, the original Cairo filter; and Template:Codeline to disable it entirely.

  <match target="font">
    <edit mode="assign" name="lcdfilter">

Advanced LCD filter specification

If the available, built-in LCD filters are not satisfactory, it is possible to tweak the font rendering very specifically by building a custom freetype2 package and modifying the hardcoded filters. If you don't know how to build and install packages from source, get acquainted with ABS first.

Note: The Infinality package allows you to tweak the filter setting with an environment variable, without recompiling.

First, refresh the freetype2 PKGBUILD as root:

# abs extra/freetype2

This example uses Template:Filename as the build directory, substitute it according to your personal ABS setup. Download and extract the freetype2 package as a regular user:

$ cd /var/abs/build
$ cp -r ../extra/freetype2 .
$ cd freetype2
$ makepkg -o

Edit the file Template:Filename and look up the definition of the constant Template:Filename:

static const FT_Byte  default_filter[5] =
    { 0x10, 0x40, 0x70, 0x40, 0x10 };

This constant defines a low-pass filter applied to the rendered glyph. Modify it as needed. Save the file, build and install the custom package:

$ makepkg -e
$ sudo pacman -Rd freetype2
$ sudo pacman -U freetype2-VERSION-ARCH.pkg.tar.xz

Reboot or restart X. The lcddefault filter should now render fonts differently.

Disable auto-hinter for bold fonts

The auto-hinter uses sophisticated methods for font rendering, but often makes bold fonts too wide. Fortunately, a solution can be turning off the autohinter for bold fonts while leaving it on for the rest:

<match target="font">
    <test name="weight" compare="more">
    <edit name="autohint" mode="assign">
Note: The Infinality package allows the autohinter to work well with bold fonts.

Enable anti-aliasing only for bigger fonts

See also for related information

Some users prefer the sharper rendering that anti-aliasing doesn't offer:

<match target="font">
    <edit name="antialias" mode="assign">

<match target="font" >
    <test name="size" qual="any" compare="more">
    <edit name="antialias" mode="assign">

<match target="font" >
    <test name="pixelsize" qual="any" compare="more">
    <edit name="antialias" mode="assign">

Replace fonts

The most reliable way to do this is to add an XML fragment similar to the one below. This will cause Bitstream Vera Sans to be used in place of Helvetica:

<match target="pattern" name="family" >
    <test name="family" qual="any" >
    <edit name="family" mode="assign">
        <string>Bitstream Vera Sans</string>

An alternate approach is to set the "preferred" font, but this only works if the original font is not on the system, in which case the one specified will be substituted:

< !-- Replace Helvetica with Bitstream Vera Sans Mono -->
< !-- Note, an alias for Helvetica should already exist in default conf files -->
    <prefer><family>Bitstream Vera Sans Mono</family></prefer>

Disable bitmap fonts

To disable bitmap fonts in fontconfig, use Template:Filename (which is not placed by fontconfig by default):

# cd /etc/fonts/conf.d
# rm 70-yes-bitmaps.conf
# ln -s ../conf.avail/70-no-bitmaps.conf

You can choose which fonts to replace bitmaps fonts with (Helvetica, Courier and Times bitmap mapts to TTF fonts) by:

# cd /etc/fonts/conf.d
# ln -s ../conf.avail/29-replace-bitmap-fonts.conf

Create bold and italic styles for incomplete fonts

Freetype has the ability to automatically create italic and bold styles for fonts that do not have them, but only if explicitly required by the application. Given programs rarely send these requests, this section covers manually forcing generation of missing styles.

Start by editing Template:Filename as explained below. Store a copy of the modifications on another file, because a font update with Template:Codeline will overwrite Template:Filename.

Assuming the Dupree font is installed:

"dupree.ttf" 0 "Dupree:style=Regular:slant=0:weight=80:width=100:foundry=unknown:index=0:outline=True:etc...

Duplicate the line, change Template:Codeline to Template:Codeline or any other style. Also change Template:Codeline to Template:Codeline for italic, Template:Codeline to Template:Codeline for bold, or combine them for bold italic:

"dupree.ttf" 0 "Dupree:style=Bold Italic:slant=100:weight=200:width=100:foundry=unknown:index=0:outline=True:etc...

Now add necessary modifications to Template:Filename:

<match target="font">
    <test name="family" qual="any">
         <!-- other fonts here .... -->
     <test name="weight" compare="more_eq"><int>140</int></test>
     <edit name="embolden" mode="assign"><bool>true</bool></edit>

<match target="font">
    <test name="family" qual="any">
        <!-- other fonts here .... -->
    <test name="slant" compare="more_eq"><int>80</int></test>
    <edit name="matrix" mode="assign">
Tip: Use the value 'embolden' for existing bold fonts in order to make them even bolder.

Change rule overriding

Fontconfig processes files in Template:Filename in reverse numerical order. This enables rules or files to override one another, but often confuses users about what file gets parsed last.

To guarantee that personal settings take precedence over any other rules, change their ordering:

# cd /etc/fonts/conf.d
# mv 50-user.conf 00-user.conf

This change seems however to be unnecessary for the most of the cases, because a user is given enough control by default to set up own font preferences, hinting and antialiasing properties, alias new fonts to generic font families, etc.

Example fontconfig configurations

Example fontconfig configurations can be found on this page.

Patched packages

These patched packages are available in the AUR and easily installable by using an AUR helper. A few considerations:

  • Configuration is usually necessary.
  • The new font rendering will not kick in until applications restart.

Original LCD packages

Cairo 1.10 in [extra] adds support for the LCD filter. See #LCD filter. You can install fontconfig-lcd from the AUR to enable the Template:Codeline filter automatically.

In order to get filtering with apps using libXft for font drawing, you need to install libxft-lcd from the AUR.


Ubuntu uses the original LCD patched packages and adds extra configurations, and occasionally patches.

Install the patched packages from the AUR. The package names are:

freetype2-ubuntu fontconfig-ubuntu libxft-ubuntu cairo-ubuntu


Note: The -cleartype packages are out of date. Consider using the newer freetype2-infinality package instead. You can set the FIR filter environment variable to match what the cleartype patches used to give.

These packages attempted to emulate ClearType, a type of subpixel rendering and filtering that is used by Windows.


The infinality patchset aims to greatly improve freetype2 font rendering. It adds multiple new capabilities, all of which are configurable via environment variables in Template:Filename.

  • Emboldening Enhancement: Disables Y emboldening, producing a much nicer result on fonts without bold versions. Works on native TT hinter and autohinter.
  • Auto-Autohint: Automatically forces autohint on fonts that contain no TT instructions.
  • Autohint Enhancement: Makes autohint snap horizontal stems to pixels. Gives a result that appears like a well-hinted truetype font, but is 100% patent-free (as far as I know).
  • Customized FIR Filter: Select your own filter values at runtime. Works on native TT hinter and autohinter.
  • Stem Alignment: Aligns bitmap glyphs to optimized pixel boundaries. Works on native TT hinter and autohinter.
  • Pseudo Gamma Correction: Lighten and darken glyphs at a given value, below a given size. Works on native TT hinter and autohinter.
  • Embolden Thin Fonts: Embolden thin or light fonts so that they are more visible. Works on autohinter.

freetype2-infinality can be installed from the AUR.

Additionally, if you are using lib32-freetype2 from [multilib], replace it with lib32-freetype2-infinality from the AUR.

In order to get filtering with apps using libXft for font drawing, you need to install libxft-lcd from the AUR.

Note: The infinality package is designed to work with this local.conf. You will most likely want to make changes to the configuration before using it (it makes a lot of font replacements, and sets the preferred fonts to Arial, Times New Roman and Consolas.)

Reverting to unpatched packages

To restore the unpatched packages, reinstall the originals:

# pacman -S --asdeps freetype2 libxft cairo fontconfig

Applications without fontconfig support

Some applications like LibreOffice will ignore fontconfig settings. This is very apparent when using the infinality patches which are heavily reliant on proper configuration. You can work around this by using ~/.Xresources, but it isn't nearly as flexible as fontconfig. Example (see #Fontconfig configuration for explanations of the options):


Make sure the settings are loaded properly when X starts with xrdb -q (see Xresources for more info).


Distorted fonts

Main article: Xorg#Display Size and DPI

Fontconfig should be able to detect DPI parameters as discovered by the Xorg server and be able to display the fonts correctly using the Xft.dpi variable. To find out if Xft.dpi has already been set correctly, check by running the program xrdb -query:

# xrdb -query | grep dpi 

If Xft.dpi was not set correctly try to fix the Xorg configuration to specify the correct dpi for your monitor.

Those still having problems can still fall back to setting it manually:

<match target="pattern">
   <edit name="dpi" mode="assign"><double>96</double></edit>

If fonts are still unexpectedly large or small, or are poorly proportioned, the Xorg server may be incorrectly detecting the DPI setting.

Missing characters

If using Emacs, the Template:Package Official and Template:Package Official packages need to be installed.

Older GTK and QT applications

Modern GTK apps enable Xft by default but this was not the case before version 2.2. If it is not possible to update these applications, force Xft for old GNOME applications by adding to Template:Filename:

export GDK_USE_XFT=1

For older QT applications:

export QT_XFT=true