Font configuration
Fontconfig is a library designed to provide a list of available fonts to applications, and also for configuration for how fonts get rendered. The FreeType library renders the fonts, based on this configuration. The freetype2 font rendering packages on Arch Linux include the bytecode interpreter (BCI) enabled for better font rendering especially with an LCD monitor. See #Fontconfig configuration and Font configuration/Examples.
Though Fontconfig is used often in modern Unix and Unix-like operating systems, some applications rely on the original method of font selection and display, the X Logical Font Description.
Font paths
For fonts to be known to applications, they must be cataloged for easy and quick access.
The font paths initially known to Fontconfig are: /usr/share/fonts/, ~/.local/share/fonts (and ~/.fonts/, now deprecated). Fontconfig will scan these directories recursively. For ease of organization and installation, it is recommended to use these font paths when adding fonts.
To see a list of known Fontconfig fonts:
$ fc-list : file
See fc-list(1) for more output formats.
Check for Xorg's known font paths by reviewing its log:
$ grep /fonts ~/.local/share/xorg/Xorg.0.log
- You can also check the list of Xorg's known font paths using the command
xset q. - Use
/var/log/Xorg.0.logif Xorg is run with root privileges.
Keep in mind that Xorg does not search recursively through the /usr/share/fonts/ directory like Fontconfig does. To add a path, the full path must be used:
Section "Files"
FontPath "/usr/share/fonts/local/"
EndSection
For more details about Xorg configuration read, Xorg#Configuration. If you want font paths to be set on a per-user basis, you can add and remove font paths from the default by adding the following line(s) to ~/.xinitrc:
xset +fp /usr/share/fonts/local/ # Prepend a custom font path to Xorg's list of known font paths xset -fp /usr/share/fonts/sucky_fonts/ # Remove the specified font path from Xorg's list of known font paths
To see a list of known Xorg fonts use xlsfonts, from the xorg-xlsfonts package.
Fontconfig configuration
Fontconfig is documented in the fonts-conf(5) man page.
Configuration can be done per-user through $XDG_CONFIG_HOME/fontconfig/fonts.conf (usually $HOME/.config/fontconfig/fonts.conf), and globally with /etc/fonts/local.conf. The settings in the per-user configuration have precedence over the global configuration. Both these files use the same syntax.
- The
50-user.confpreset need to be enabled to make the user configuration take effect, and the51-local.confpreset is for the global configuration. Check the #Presets section to know how to enable these presets. - Configuration files and directories:
~/.fonts.conf/,~/.fonts.conf.d/and~/.fontconfig/*.cache-*are deprecated and will not be read by default in the future versions of the package. New paths are$XDG_CONFIG_HOME/fontconfig/fonts.conf,$XDG_CONFIG_HOME/fontconfig/conf.d/NN-name.confand$XDG_CACHE_HOME/fontconfig/*.cache-*respectively. If using the second location, make sure the naming is valid (whereNNis a two digit number like00,10, or99).
Fontconfig gathers all its configurations in a central file (/etc/fonts/fonts.conf). This file is replaced during fontconfig updates and should not be edited. Fontconfig-aware applications source this file to know available fonts and how they get rendered; simply restarting such applications is sufficient to load the new configuration. This file is a conglomeration of rules from the global configuration (/etc/fonts/local.conf), the configured presets in /etc/fonts/conf.d/, and the user configuration file ($XDG_CONFIG_HOME/fontconfig/fonts.conf). fc-cache can be used to rebuild fontconfig's configuration, although changes will only be visible in newly launched applications.
Fontconfig configuration files use XML format and need these headers:
<?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> <fontconfig> <!-- settings go here --> </fontconfig>
The configuration examples in this article omit these tags.
Presets
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
Anti-aliasing
Font rasterization converts vector font data to bitmap data so that it can be displayed. The result can appear jagged due to aliasing. The technique known as anti-aliasing can be used to increase the apparent resolution of font edges. Anti-aliasing is enabled by default. To disable it:
<match target="font">
<edit name="antialias" mode="assign">
<bool>false</bool>
</edit>
</match>
Hinting
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.
Byte-Code Interpreter (BCI)
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:
<match target="font">
<edit name="hinting" mode="assign">
<bool>false</bool>
</edit>
</match>
/etc/profile.d/freetype2.sh. The interpreter is set by passing the parameter truetype:interpreter-version=NN, NN corresponding to the version chosen, to the FREETYPE_PROPERTIES variable in the script. The most popular values are:
- 35 for classic mode (emulates Windows 98),
- 36 for classic Windows ClearType style (before Windows XP),
- 38 for "Infinality" mode (highly configurable rendering, considered slow and discontinued),
- 40 for minimal mode (stripped down Infinality, this is the default).
Autohinter
The autohinter attempts to do automatic hinting and disregards any existing hinting information. 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 later kind so autohinter will not be useful. Autohinter is disabled by default. To enable it:
<match target="font">
<edit name="autohint" mode="assign">
<bool>true</bool>
</edit>
</match>
Hintstyle
Hintstyle is the amount of font reshaping done to line up to the grid. Hinting values are: hintnone, hintslight, hintmedium, and hintfull. hintslight will make the font more fuzzy to line up to the grid but will be better in retaining font shape (see [2]), while hintfull will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. hintslight implicitly uses the autohinter in a vertical-only mode in favor of font-native information for non-CFF (.otf) fonts.
hintslight is the default setting. To change it:
<match target="font">
<edit name="hintstyle" mode="assign">
<const>hintnone</const>
</edit>
</match>
Pixel alignment
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.
<match target="font">
<edit name="rgba" mode="assign">
<const>rgb</const>
</edit>
</match>
Subpixel rendering
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 (FT_CONFIG_OPTION_SUBPIXEL_RENDERING) [3].
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 [4].
lcdlight LCD filter to get the subpixel rendering behavior prior FreeType 2.10.3, called Harmony (instead of ClearType).LCD filter
When using ClearType subpixel rendering, you should enable the LCD filter, which is designed to reduce colour 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 lcddefault filter will work for most users. Other filters are available that can be used in special situations: lcdlight; a lighter filter ideal for fonts that look too bold or fuzzy, lcdlegacy, the original Cairo filter; and lcdnone to disable it entirely.
<match target="font">
<edit name="lcdfilter" mode="assign">
<const>lcddefault</const>
</edit>
</match>
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. The Arch Build System can be used to build and install packages from source. This requires installation of the asp package.
Checkout the freetype2 PKGBUILD and download/extract the build files:
$ asp checkout freetype2 $ cd freetype2/trunk $ makepkg -o
Enable ClearType subpixel rendering by editing the file src/freetype-VERSION/include/freetype/config/ftoption.h and uncommenting the FT_CONFIG_OPTION_SUBPIXEL_RENDERING macro.
Then, edit the file src/freetype-VERSION/src/base/ftlcdfil.c and look up the definition of the constant default_filter[5]:
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.
Custom settings for certain fonts or font styles
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">
<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>
...
Replace or set default fonts
The most reliable way to set a default font is to add an XML fragment similar to the one below. Using the "binding" attribute will give you better results, for example, this will cause Ubuntu to be used in place of Georgia:
... <match target="pattern"> <test qual="any" name="family"><string>Georgia</string></test> <edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit> </match> ...
An alternate approach is to set the "preferred" font. Fonts matching the <family> element are edited to prepend the list of <prefer>ed families before the matching <family>. This only works if the original font is not in 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 -->
<alias>
<family>Helvetica</family>
<prefer>
<family>Bitstream Vera Sans Mono</family>
</prefer>
</alias>
...
Whitelisting and blacklisting fonts
The element <selectfont> is used in conjunction with the <acceptfont> and <rejectfont> elements to selectively whitelist or blacklist fonts from the resolve list and match requests. The simplest and most typical use case it to reject one font that is needed to be installed, however is getting matched for a generic font query that is causing problems within application user interfaces.
First obtain the Family name as listed in the font itself:
$ fc-scan .fonts/lklug.ttf --format='%{family}\n'
LKLUG
Then use that Family name in a <rejectfont> stanza:
<selectfont>
<rejectfont>
<pattern>
<patelt name="family" >
<string>LKLUG</string>
</patelt>
</pattern>
</rejectfont>
</selectfont>
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 <acceptfont> is used after it to whitelist individual fonts out of the larger blacklisted group.
<selectfont>
<rejectfont>
<glob>/usr/share/fonts/OTF/*</glob>
</rejectfont>
<acceptfont>
<pattern>
<patelt name="family" >
<string>Monaco</string>
</patelt>
</pattern>
</acceptfont>
</selectfont>
Disable bitmap fonts
Bitmap fonts are sometimes used as fallbacks for missing fonts, which may cause text to be rendered pixelated or too large. Use the 70-no-bitmaps.conf preset to disable this behavior.
To disable embedded bitmap for all fonts:
~/.config/fontconfig/conf.d/20-no-embedded.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
<match target="font">
<edit name="embeddedbitmap" mode="assign">
<bool>false</bool>
</edit>
</match>
</fontconfig>
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>
Disable scaling of bitmap fonts
To disable scaling of bitmap fonts (which often makes them blurry), remove /etc/fonts/conf.d/10-scale-bitmap-fonts.conf.
Note this can break the scaling of emoji fonts such as Segoe UI Emoji, making them huge.
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 /usr/share/fonts/fonts.cache-1 as explained below. Store a copy of the modifications on another file, because a font update with fc-cache will overwrite /usr/share/fonts/fonts.cache-1.
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 style=Regular to style=Bold or any other style. Also change slant=0 to slant=100 for italic, weight=80 to weight=200 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 $XDG_CONFIG_HOME/fontconfig/fonts.conf:
...
<match target="font">
<test name="family" qual="any">
<string>Dupree</string>
<!-- other fonts here .... -->
</test>
<test name="weight" compare="more_eq"><int>140</int></test>
<edit name="embolden" mode="assign"><bool>true</bool></edit>
</match>
<match target="font">
<test name="family" qual="any">
<string>Dupree</string>
<!-- other fonts here .... -->
</test>
<test name="slant" compare="more_eq"><int>80</int></test>
<edit name="matrix" mode="assign">
<times>
<name>matrix</name>
<matrix>
<double>1</double><double>0.2</double>
<double>0</double><double>1</double>
</matrix>
</times>
</edit>
</match>
...
embolden for existing bold fonts in order to make them even bolder.Rule priority
Fontconfig processes files in /etc/fonts/conf.d in numerical order. Therefore the rules of 01-aaa.conf and 02-bbb.conf will have the same effect as a single 01-aaabbb.conf file containing first the rules of 01-aaa then the ones of 02-bbb.
Usually that means the files with the smaller prefix will have higher precedence. However, the fontconfig syntax is flexible and allows that a new rule takes 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 $XDG_CONFIG_HOME/fontconfig/fonts.conf and in the directory $XDG_CONFIG_HOME/fontconfig/conf.d 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.
Query the current settings
To find out what settings are in effect, use fc-match --verbose. eg.
$ fc-match --verbose Sans
family: "DejaVu Sans"(s) hintstyle: 3(i)(s) hinting: True(s) ...
Look up the meaning of the numbers at fonts-conf(5) Eg. 'hintstyle: 3' means 'hintfull'
Applications without fontconfig support
Some applications like URxvt will ignore fontconfig settings. You can work around this by using ~/.Xresources, but it is not as flexible as fontconfig. Example (see #Fontconfig configuration for explanations of the options):
~/.Xresources
Xft.autohint: 0 Xft.lcdfilter: lcddefault Xft.hintstyle: hintslight Xft.hinting: 1 Xft.antialias: 1 Xft.rgba: rgb
Make sure the settings are loaded properly when X starts with xrdb -q (see X resources for more information).
Troubleshooting
Distorted fonts
If fonts are still unexpectedly large or small, poorly proportioned or simply rendering poorly, fontconfig may be using the incorrect DPI.
Fontconfig should be able to detect DPI parameters as discovered by the Xorg server. You can check the automatically discovered DPI with xdpyinfo (provided by the xorg-xdpyinfo package):
$ xdpyinfo | grep dots
resolution: 102x102 dots per inch
If the DPI is detected incorrectly (usually due to an incorrect monitor EDID), you can specify it manually in the Xorg configuration, see Xorg#Display size and DPI. This is the recommended solution, but it may not work with buggy drivers.
Fontconfig will default to the Xft.dpi variable if it is set. Xft.dpi is usually set by desktop environments (usually to Xorg's DPI setting) or manually in ~/.Xdefaults or ~/.Xresources. Use xrdb to query for the value:
$ xrdb -query | grep dpi
Xft.dpi: 102
Those still having problems can fall back to manually setting the DPI used by fontconfig:
... <match target="pattern"> <edit name="dpi" mode="assign"><double>102</double></edit> </match> ...
Calibri, Cambria, Monaco, etc. not rendering properly
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.
Applications overriding hinting
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 smplayer. Use the specific configuration program for the application in such cases. For GNOME, try gnome-tweaks.
Applications not picking up hinting from GNOME settings
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 fonts.conf file:
<?xml version='1.0'?> <!DOCTYPE fontconfig SYSTEM 'urn:fontconfig:fonts.dtd'> <fontconfig> <match target="font"> <edit mode="assign" name="hinting"> <bool>false</bool> </edit> </match> </fontconfig>
In this example, hinting is set to "grayscale".
Incorrect hinting in GTK applications
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 xsettingsd or xsettingsd-gitAUR 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:
~/.xsettingsd
Xft/Hinting 1 Xft/HintStyle "hintslight" Xft/Antialias 1 Xft/RGBA "rgb"
If that is not working in some other applications, you could install xorg-xrdb and provide the following configuration:
~/.Xresources
Xft.hinting: 1 Xft.hintstyle: hintslight Xft.antialias: 1 Xft.rgba: rgb
Then you can execute the script xrdb -merge ~/.Xresources at every system startup to apply the options. See also X resources and #Applications without fontconfig support.
Helvetica font problem in generated PDFs
If the following command
fc-match helvetica
produces
helvR12-ISO8859-1.pcf.gz: "Helvetica" "Regular"
then the bitmap font provided by xorg-fonts-75dpi 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 xorg group (which is usually NOT recommended). To solve the pixelized font problem, you can uninstall the package. Install gsfonts (Type 1) or tex-gyre-fonts (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.
FreeType breaking bitmap fonts
Some users are reporting problems (FS#52502) with bitmap fonts having changed names after upgrading freetype2 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 [5]. Users transitioning from the old format might want to create a font alias to remedy the problems, like the solution which is described in [6], given here too:
Assume we want to create an alias for terminus-font, which was renamed from Terminus to xos4 Terminus in the previously described freetype2 update:
- Create a configuration file in
/etc/fonts/conf.avail/for the font alias:
/etc/fonts/conf.avail/33-TerminusPCFFont.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
<alias>
<family>Terminus</family>
<prefer><family>xos4 Terminus</family></prefer>
<default><family>fixed</family></default>
</alias>
</fontconfig>
- Create a symbolic link towards it in the
/etc/fonts/conf.ddirectory. In our example we would link as follows:ln -s /etc/fonts/conf.avail/33-TerminusPCFFont.conf /etc/fonts/conf.dto 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 .Xresources or restart the display server first so the affected programs can use the alias.
Underscores not rendered with Dejavu Monospace
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 #Replace or set default fonts.
Debugging FreeType fonts
freetype2-demos provides tools for debugging FreeType font configuration. ftview 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