Regenerate MIME Associations Safely with update-mime

Install or remove a package and update-mime often runs by itself through a dpkg trigger. When you need to run it by hand it pays to test in your own home directory first, and these examples use update-mime from mailcap package version 3.70+nmu1ubuntu1.24.04.1.

You will rebuild the mailcap database that MIME-aware programs read, see where the generated file comes from, and test a user-local copy before touching the system configuration. Allow about fifteen minutes. You need a shell and the mailcap package; reading inputs and generating a local copy needs no privileges, updating the system file does. This guide does not touch service configuration or restart anything.

1. Confirm the installed command

Check which executable runs and record the package version:

$ command -v update-mime
/usr/sbin/update-mime
$ dpkg-query -W -f='${Package} ${Version}\n' mailcap
mailcap 3.70+nmu1ubuntu1.24.04.1

The command takes no positional parameters. Its whole job is updating /etc/mailcap so it reflects the MIME information supplied by installed packages and desktop entries.

2. Understand the generated inputs

Packages that provide MIME handlers drop mailcap entries into /usr/lib/mime/packages, ordinary mailcap lines pairing a MIME type with a viewer command and semicolon-separated options. Package installation and removal can already trigger update-mime, so a manual run is mostly useful after inspecting or changing inputs, or repairing a broken generated file.

The command also reads desktop entries from /usr/share/applications/, which become mailcap entries at lower priority than anything from /usr/lib/mime/packages. A handler showing up in a desktop file does not outrank a package-provided one.

For a quick inventory, read-only commands are enough:

$ find /usr/lib/mime/packages -maxdepth 1 -type f -printf '%f\n' | head
vim-common
lynx-common
man-db
unzip
info

Your list will differ. Do not edit a package's own file to change local preference: that is what the ordering file in the next step is for.

3. Test a complete user-local database

$ update-mime --local
$ test -s "$HOME/.mailcap" && printf '%s\n' 'local mailcap generated'
local mailcap generated
$ sed -n '1,14p' "$HOME/.mailcap"
###############################################################################
#
#  MIME media types and programs that process those types
#

The generated file has a user section followed by generated entries. The exact handler list depends on your installed packages and desktop files, so verify by searching for the type or command you actually care about:

$ grep -n '^text/plain;' "$HOME/.mailcap"
text/plain; less; copiousoutput

That line is illustrative of one local configuration, not a promise every host matches it. Nothing found means check the package input and the MIME type spelling before you go near the system database.

4. Control handler ordering

To change the order in the system database, edit /etc/mailcap.order; for a local database, edit ~/.mailcap.order. Read mailcap.order(5) on this machine before writing a rule, since its syntax decides how package names get ranked.

• The order file ranks entries; it does not create them. A handler is created by a package supplying a file under /usr/lib/mime/packages, and that entry needs a real viewer command, or false when there deliberately isn't one.
• Priority is a separate mailcap option, 0 to 9. 0 is lowest, 9 highest, and an omitted priority defaults to 5. A class/* rule should usually sit below a specific type, and */* at priority 0 is generally a last resort.

5. Regenerate the system file

$ sudo cp --preserve=all /etc/mailcap /etc/mailcap.before-update-mime
$ sudo update-mime
$ test -s /etc/mailcap && printf '%s\n' 'system mailcap generated'
system mailcap generated

sudo is needed because the command writes under /etc. A successful run prints nothing useful; the real verification is the file check plus a targeted search:

$ grep -n '^text/plain;' /etc/mailcap
text/plain; less; copiousoutput

Do not assume the handler shown here is the one a particular mail reader will actually use. The reader can apply its own rules, and the entry it picks can depend on tests, priorities and whether a terminal is available.

6. Recover if the regenerated result is wrong

First work out whether the problem is ordering, a missing package entry, or a consumer-specific rule. Never delete /etc/mailcap outright: that just removes the generated database without fixing whatever fed it.

$ sudo cp --preserve=all /etc/mailcap.before-update-mime /etc/mailcap
$ test -s /etc/mailcap && printf '%s\n' 'previous mailcap restored'
previous mailcap restored

That restores file contents only. If a package was installed or removed, leave the package state alone and go look at its input under /usr/lib/mime/packages instead. Once you understand the cause, run sudo update-mime again. A later package trigger can regenerate the file anyway, so keep a deliberate ordering rule in /etc/mailcap.order rather than relying on hand edits to generated output.