Rebuild X fonts.dir Safely with update-fonts-dir

Install or remove a package that shares an X font directory, and update-fonts-dir is the tool that rebuilds the stale index.

It works from the directory's final name, not its full path.

This guide uses Debian's xfonts-utils package, installed here as version 1:7.7+6build3. Allow about ten minutes.

• Needs: a shell, an X font directory, and permission to write its generated index. Reading the help and checking a directory is unprivileged; rebuilding a system directory normally requires sudo.

1. Confirm the command and layout

Check which executable is being used and read its installed help:

$ command -v update-fonts-dir
/usr/sbin/update-fonts-dir
$ update-fonts-dir --help
Usage: update-fonts-dir DIRECTORY ...
       update-fonts-dir { -7 | --x11r7-layout } DIRECTORY ...
       update-fonts-dir { -h | --help }

The command has two layouts. Without an option, it looks below /usr/lib/X11/fonts/. With --x11r7-layout, also written -7, it looks below /usr/share/fonts/X11/. The latter is the layout on this machine, so the examples below use --x11r7-layout.

2. Inspect the target directory

The operand is only the final directory component. For /usr/share/fonts/X11/misc, the operand is misc, not the full path:

$ test -d /usr/share/fonts/X11/misc && echo 'directory exists'
directory exists
$ find /usr/share/fonts/X11/misc -maxdepth 1 -type f \( -name 'fonts.scale' -o -name '*.pcf.gz' -o -name '*.otf' -o -name '*.ttf' \) -print | sed -n '1,8p'

update-fonts-dir builds the index from the directory's fonts.scale and font files. It does not take a font file as an operand, and it accepts more than one final directory name, so a package script can update several directories in one invocation.

Do not pass /usr/share/fonts/X11/misc as the normal operand. The installed command warns that absolute paths are deprecated, and the manual documents the final-component form as the supported usage.

3. Back up the generated index

Rebuilding changes fonts.dir. Before an administrative change, preserve the existing file if one is present:

$ sudo cp --preserve=all \
    /usr/share/fonts/X11/misc/fonts.dir \
    /usr/share/fonts/X11/misc/fonts.dir.before-update

If the file does not exist yet, cp fails and no backup gets made. That is harmless; check first if you prefer:

$ if test -e /usr/share/fonts/X11/misc/fonts.dir; then
    sudo cp --preserve=all /usr/share/fonts/X11/misc/fonts.dir \
        /usr/share/fonts/X11/misc/fonts.dir.before-update
    echo 'backup created'
else
    echo 'no existing fonts.dir to back up'
fi

4. Rebuild fonts.dir

Run the command with the layout option and the final directory name:

$ sudo update-fonts-dir --x11r7-layout misc

On success, the command normally has no useful standard output. Verify its exit status immediately:

$ printf '%s\n' "$?"
0

The command invokes mkfontdir with the right arguments and writes the generated index in the selected X font directory. A successful status means the operation completed; it does not prove every font is valid or that an X server is currently using the directory.

To update the older layout instead, use the corresponding final component below /usr/lib/X11/fonts/ and omit --x11r7-layout:

$ sudo update-fonts-dir misc

Do not run both commands for the same directory name unless both directories genuinely exist and you intend to maintain both indexes.

5. Verify the generated file

Check that the expected file exists, is owned sensibly for the directory, and contains a count followed by font entries:

$ sudo test -s /usr/share/fonts/X11/misc/fonts.dir
$ sudo sed -n '1,8p' /usr/share/fonts/X11/misc/fonts.dir
<number of fonts>
<font-file> <font-name>
...

The exact count and font names depend on the installed packages, so do not copy the placeholder output literally. Compare the result with what you saw in step 2. If an expected package's fonts are missing, check that its font files and any fonts.scale file are actually in this directory before rebuilding again.

For a second, non-destructive check, ask mkfontdir or the X font tooling available on your system to inspect the directory. This guide does not assume those optional commands are installed beyond the dependency update-fonts-dir itself uses.

6. Handle errors and undo the change

An invocation without directories is an argument error with status 2. An unrecognised option also has status 2. A fatal path error has status 1. A directory that does not exist is reported as a warning and skipped, so a command can finish with status 0 even though that particular directory was not updated:

$ update-fonts-dir clearly-not-a-font-directory
warning: ...clearly-not-a-font-directory does not exist or is not a directory
$ printf '%s\n' "$?"
0

That warning is easy to miss in a script. Check that every operand exists first, and treat warnings in the command's output as failures for your deployment process.

If the new file is wrong, restore the backup. This is a privileged, state-changing operation, so confirm the paths before pressing Enter:

$ sudo cp --preserve=all \
    /usr/share/fonts/X11/misc/fonts.dir.before-update \
    /usr/share/fonts/X11/misc/fonts.dir
$ sudo sed -n '1,4p' /usr/share/fonts/X11/misc/fonts.dir