Rebuild an X Font Directory's fonts.scale Safely

A scalable font package installs cleanly but the X server still can't see it, and update-fonts-scale is the tool that regenerates the missing index.

It rebuilds the generated fonts.scale file for an X font directory from the scalable-font indexes installed under /etc/X11/fonts/. The installed command is from xfonts-utils version 1:7.7+6build3. Allow about ten minutes, including a check of the source indexes.

This is an administrative operation. Reading the inputs is normally unprivileged, but rebuilding a system font directory usually needs elevated privileges. The command can replace or remove a generated file, so do not run it casually on a production host or during an X service change.

1. Check the installed command

Confirm the command comes from the expected package and inspect the version-specific help. These checks do not change files:

$ command -v update-fonts-scale
/usr/sbin/update-fonts-scale
$ dpkg-query -W -f='${Package} ${Version}\n' xfonts-utils
xfonts-utils 1:7.7+6build3
$ update-fonts-scale --help
Usage: update-fonts-scale DIRECTORY ...
       update-fonts-scale { -h | --help }
...

The only documented option is -h/--help. Normal use needs one or more directory operands.

Checkpoint: If the package or command is absent, stop here and use your normal package-management process. Do not create a replacement script with a similar name.

2. Understand the directory argument

Pass the final component of the X font directory, such as Type1, 75dpi or misc. The command uses that name to find package indexes in /etc/X11/fonts/DIRECTORY/*.scale and to update the corresponding X font directory under /usr/share/fonts/X11/ on this installation.

$ find /etc/X11/fonts/Type1 -maxdepth 1 -type f -name '*.scale' -print
/etc/X11/fonts/Type1/xfonts-scalable.scale
/etc/X11/fonts/Type1/fonts-urw-base35.scale
$ find /usr/share/fonts/X11/Type1 -maxdepth 1 -type f -name '*.pfb' -print | head

Your package names and font files will differ. The .scale files are indexes supplied by font packages; they are not the generated output. Check that the source directory and destination directory are both the ones you intend to operate on.

Do not use a full path as the routine form. update-fonts-scale Type1 is the documented form. An absolute path is accepted by this installed version with a deprecation warning, but a path into /etc/X11/fonts/ is rejected as the wrong kind of directory. Using the basename avoids both traps.

3. Inspect the indexes before changing state

Look at the beginning of each index and confirm its referenced font files exist in the destination directory. The first field is the filename; the rest describes its X Logical Font Description:

$ sed -n '1,8p' /etc/X11/fonts/Type1/xfonts-scalable.scale
$ while read -r fontfile fontname; do
    test -f "/usr/share/fonts/X11/Type1/$fontfile" || printf 'missing: %s\n' "$fontfile"
  done < /etc/X11/fonts/Type1/xfonts-scalable.scale

A missing file can be normal after a package has been removed but not purged. During a rebuild, the command skips such entries and, when DEBUG is non-empty, reports them on standard error. A missing file that should still be installed points to a package or filesystem problem; fix that first rather than hiding it behind a generated index.

4. Rebuild the generated index

Once the inputs look correct, run the command with the basename. This changes the system font directory, so use sudo only when your account cannot write there:

$ sudo update-fonts-scale Type1
$ printf 'exit status: %s\n' "$?"
exit status: 0

The normal successful run is quiet. It combines matching package indexes, keeps only entries whose font files exist, writes a new count at the top, and replaces /usr/share/fonts/X11/Type1/fonts.scale. It does not change the package-provided *.scale files.

Warning: If no matching index files exist, the command removes an existing generated fonts.scale and may remove the destination directory if it is empty. That is why inspecting the source directory first matters: keep the package indexes intact as your recovery source.

5. Verify the result

Check the generated file and its count without editing it:

$ test -f /usr/share/fonts/X11/Type1/fonts.scale && sed -n '1,5p' /usr/share/fonts/X11/Type1/fonts.scale
12
...
$ awk 'NR == 1 { expected = $1; next } END { print "entries:", NR - 1, "declared:", expected }' /usr/share/fonts/X11/Type1/fonts.scale
entries: 12 declared: 12

The first line should equal the number of subsequent font entries. If the file is absent, check the source directory and the command's exit status. A status of 0 means the utility completed its work; it does not mean every package index was logically correct.

For troubleshooting, rerun with a temporary debugging environment. This still performs the rebuild:

$ sudo env DEBUG=1 update-fonts-scale Type1
note: /etc/X11/fonts/Type1/example.scale references nonexistent font file missing.pfb; skipping

The exact filename and wrapping vary. Do not treat a debug note as proof the resulting font name is usable; verify the file and refresh the X font consumer only if your system's font service requires it.

6. Recover from a bad rebuild

There is no undo option. Recovery is to restore the package indexes or reinstall the package that owns the missing font files, then run update-fonts-scale DIRECTORY again. If a previous generated file was locally customised, recover it from your filesystem backup rather than copying an arbitrary file from another host.

For an invalid operand, status 2 indicates invalid arguments; status 1 indicates a fatal error. The command may warn and skip a directory that does not exist, so read standard error even when the final status is zero. Never use /etc/X11/fonts/Type1 as the operand: it is the index directory, not the X font directory.

Done means