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

You will rebuild the generated fonts.dir file for an X font directory, using the directory's final name rather than its full path. This is useful after installing or removing packages that share an X font directory. The guide uses Debian's xfonts-utils package, installed here as version 1:7.7+6build3.

Allow about ten minutes. You need 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 used by 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. It also 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 will fail and no backup will be 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 appropriate arguments and writes the generated index in the selected X font directory. A successful status means the operation completed; it does not prove that 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 really 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 the files you saw in step 2. If an expected package's fonts are absent, 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 used by update-fonts-dir.

6. Handle errors and undo the change

An invocation without directories is an argument error and exits 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

Once the replacement has been tested and you no longer need the recovery copy, remove it explicitly with sudo rm. That deletion is irreversible; retaining it costs little and is safer during troubleshooting.