Font configuration

There are presets installed in the directory /usr/share/fontconfig/conf.avail. They can be enabled by creating symbolic links to them, both per-user and globally, as described in /etc/fonts/conf.d/README. 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 /usr/share/fontconfig/conf.avail/10-sub-pixel-rgb.conf

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

$ mkdir $XDG_CONFIG_HOME/fontconfig/conf.d
$ ln -s /usr/share/fontconfig/conf.avail/10-sub-pixel-rgb.conf $XDG_CONFIG_HOME/fontconfig/conf.d

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

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 (i.e. the pixel grid of the display). Its intended effect is to make fonts appear more crisp so that they are more readable. Fonts will line up correctly without hinting when displays have around 300 DPI.

Using BCI hinting, instructions in TrueType fonts are rendered according to FreeTypes's interpreter. BCI hinting works well with fonts with good hinting instructions. Hinting is enabled by default. To disable it:

The autohinter attempts to do automatic hinting, disregarding any hinting information embedded in the font. Originally, it was the default because TrueType2 fonts were patent-protected, but now that these patents have expired, there is very little reason to use it. It does work better with fonts that have broken or no hinting information, but it will be strongly sub-optimal for fonts with good hinting information. Generally, common fonts are of the latter kind, so the autohinter will not be useful. The autohinter is disabled by default. To enable it:

Hintstyle is the amount of font reshaping done to line up to the grid. Hinting values are: , , , and hintfull. will make the font more fuzzy to line up to the grid but will be better in retaining font shape (see ), while hintfull will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. implicitly uses the autohinter in a vertical-only mode in favor of font-native information for non-CFF (.otf) fonts.

is the default setting. To change it:

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. Monitors are either: RGB (most common), BGR, V-RGB (vertical), or V-BGR. A monitor test can be found here.

Subpixel rendering is a technique to improve sharpness of font rendering by effectively tripling the horizontal (or vertical) resolution through the use of subpixels. On Windows machines, this technique is called ClearType.

FreeType2 provides two different types of subpixel rendering, called Harmony and ClearType () .

An LCD filter is recommended when ClearType subpixel rendering is enabled (Harmony subpixel rendering does not require setting an LCD filter). See the section below on how to enable an LCD filter and its benefits.

Starting from FreeType 2.10.3, Arch Linux enables ClearType subpixel rendering by default .

When using ClearType subpixel rendering, you should enable the LCD filter, which is designed to reduce color fringing. This is described under LCD filtering in the FreeType 2 API reference. Different options are described under FT_LcdFilter, and are illustrated by this LCD filter test page.

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

<nowiki/>
  <match target="font">
    <edit name="lcdfilter" mode="assign">
      <const>lcddefault</const>
    </edit>
  </match>

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. The Arch Build System can be used to build and install packages from source. This requires installation of the package.

Checkout the PKGBUILD and download/extract the build files:

$ asp checkout freetype2
$ cd freetype2/trunk
$ makepkg -o

Enable ClearType subpixel rendering by editing the file and uncommenting the macro.

Then, edit the file and look up the definition of the constant :

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. (reference: freetype list discussion) Save the file, build and install the custom package:

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

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

The autohinter 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">
        <const>medium</const>
    </test>
    <edit name="autohint" mode="assign">
        <bool>false</bool>
    </edit>
</match>
...

Some fonts may not look good with BCI hinting. It can be disabled for just those fonts:

...
<match target="font">
    <test name="family" qual="any">
        <string>My Font</string>
    </test>
    <edit name="hinting" mode="assign">
        <bool>false</bool>
    </edit>
</match>
...

A reliable way to set a default or fallback font is to add an XML fragment to perform a match test. With the "binding" attribute, for example, the following setting will fallback to Gentium in place of Georgia:

In the above, the "compare" attribute can be "eq" (i.e., exactly equal to Georgia), "contains" (e.g., matching either Georgia or Georgia Pro), or other values. See .

An alternate approach is to use <alias> to set the "preferred" font. Fonts matching the <family> element are edited to prepend the list of <prefer>ed families before the matching <family>. The following example will fallback to Bitstream Vera Sans when Helvetica is called:

<alias> can also be used to specify fallback fonts when some glyphs are missing. For example, many versions of Helvetica Neue do not include Greek characters. A user might have Helvetica Neue installed and want to use it for Latin characters, and fallback to FreeSans for Greek characters due to its similarity to Helvetica. However, the same user might have set another font Noto Sans as the default sans-serif font. The following will allow this to be achieved:

The above is not needed if the user simply wants to fallback to default fonts whenever glyphs are missing.

The element <selectfont> is used in conjunction with the and <rejectfont> elements to selectively whitelist or blacklist fonts from the resolve list and match requests. The simplest and most typical use case is to reject a font that the user needs installed, but is getting matched for a generic font query that is causing problems with user interfaces.

First, obtain the Family name as listed in the font itself:

Then, use that Family name in a <rejectfont> stanza:

Typically, when both elements are combined, <rejectfont> is first used on a more general matching glob to reject a large group (such as a whole directory), then is used after it to whitelist individual fonts out of the larger blacklisted group.

Bitmap fonts are sometimes used as fallbacks for missing fonts, which may cause text to be rendered pixelated or too large. Use the preset to disable this behavior.

To disable embedded bitmap for all fonts:

To disable embedded bitmap fonts for a specific font:

<match target="font">
  <test qual="any" name="family">
    <string>Monaco</string>
  </test>
  <edit name="embeddedbitmap">
    <bool>false</bool>
  </edit>
</match>

To disable scaling of bitmap fonts (which often makes them blurry), remove . Note this can break the scaling of emoji fonts such as Segoe UI Emoji, making them huge.

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 as explained below. Store a copy of the modifications on another file, because a font update with will overwrite .

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 to style=Bold or any other style. Also change to slant=100 for italic, to 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 :

Fontconfig processes files in in numerical order. Therefore, the rules of and will have the same effect as a single file first containing the rules of 01-aaa then the ones of .

Usually, that means the files with the smaller prefix will have higher precedence. However, the fontconfig syntax is flexible and allows a new rule to take precedence over an existing rule. Therefore, it is recommended to #Query the current settings to test the result of the rule interactions.

Note that the user's rules defined in and in the directory are loaded via the file /etc/fonts/conf.d/50-user.conf and typically take precedence over the rules defined in files starting with a higher number.

To find out what settings are in effect, use . eg.

Look up the meaning of the numbers at fonts-conf(5) Eg. 'hintstyle: 3' means 'hintfull'

See HiDPI for instructions on handling high or mixed DPI displays: using a DPI setting which is not matching the physical hardware can lead to fuzzy font display.

Some scalable fonts have embedded bitmap versions which are rendered instead, mainly at smaller sizes. Using Metric-compatible fonts as replacements can improve the rendering in these cases.

You can also force using scalable fonts at all sizes by disabling embedded bitmap, sacrificing some rendering quality.

Some applications or desktop environments may override default fontconfig hinting and anti-aliasing settings. This may happen with GNOME 3, for example while you are using Qt applications like vlc or . Use the specific configuration program for the application in such cases. For GNOME, try .

For instance, under GNOME it sometimes happens that Firefox applies full hinting even when it is set to "none" in GNOME's settings, which results in sharp and widened fonts. In this case you would have to add hinting settings to your file:

In this example, hinting is set to "grayscale".

In some desktop environments, especially outside GNOME and Plasma, some GTK applications could not read font configuration properly. In order to solve this issue, install or xsettingsd-git^AUR and execute it at every system startup. See also Xsettingsd and xsettingsd wiki for more information. It can be configured with the following common configuration:

If that is not working in some other applications, you could install and provide the following configuration:

Then you can execute the script at every system startup to apply the options. See also X resources and #Applications without fontconfig support.

GTK4 and libadwaita programs ignore font hinting settings. To remedy this, create or modify the following configuration:

~/.config/gtk-4.0/settings.ini

[Settings]
gtk-hint-font-metrics=true

See also the GTK documentation and GTK issue 3787.

If the following command

fc-match helvetica

produces

helvR12-ISO8859-1.pcf.gz: "Helvetica" "Regular"

then the bitmap font provided by is likely to be embedded into PDFs generated by "Print to File" or "Export" in various applications. The bitmap font was probably installed as a consequence of installing the whole group (which is usually NOT recommended). To solve the pixelized font problem, you can uninstall the package. Install (Type 1) or (OpenType) for corresponding free subsitute of Helvetica (and other PostScript/PDF base fonts).

You may also experience similar problem when you open a PDF which requires Helvetica but does not have it embedded for viewing.

Some users are reporting problems () with bitmap fonts having changed names after upgrading to version 2.7.1, creating havoc in terminal emulators and several other programs such as dwm or dmenu by falling back to another (different) font. This was caused by the changes to the PCF font family format, which is described in their release notes . Users transitioning from the old format might want to create a font alias to remedy the problems, like the solution which is described in , given here too:

Assume we want to create an alias for , which was renamed from to xos4 Terminus in the previously described update:

• Create a configuration file in /etc/fonts/conf.avail/ for the font alias:

• Create a symbolic link towards it in the directory. In our example we would link as follows: to make the change permanent.

Everything should now work as it did before the update, the font alias should not be in effect, but make sure to either reload or restart the display server first so the affected programs can use the alias.

Since Pango 1.44, the underscore characters disappear with certain font sizes when using the DejaVu Sans Mono font. A workaround is to use Liberation Mono as the monospace font, see #Set default or fallback fonts.

provides tools for debugging FreeType font configuration.  is a GUI in which you can tweak font rendering settings with a live preview. For example:

$ ftview -e unic -d 1024x768x24 -r 96 10 /usr/share/fonts/noto/NotoSans-Regular.ttf