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.
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.1The 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.
Checkpoint: if command -v finds nothing, repair the package installation through your normal package-management process. Do not download a replacement script into /usr/sbin.
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
infoYour 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.
Checkpoint: use --local before you go anywhere near /etc. This mode writes a complete .mailcap in your own home directory instead of /etc/mailcap, and looks for ordering overrides in ~/.mailcap.order.
$ 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; copiousoutputThat 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.
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.
/usr/lib/mime/packages, and that entry needs a real viewer command, or false when there deliberately isn't one.class/* rule should usually sit below a specific type, and */* at priority 0 is generally a last resort.Warning: the default mode rewrites the generated system database. Back it up first if the current file is valuable or you are chasing a regression:
$ 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 generatedsudo 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; copiousoutputDo 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.
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.
Recovery: if you made the backup in step 5 and need an immediate rollback, restore it with elevated privileges:
$ sudo cp --preserve=all /etc/mailcap.before-update-mime /etc/mailcap
$ test -s /etc/mailcap && printf '%s\n' 'previous mailcap restored'
previous mailcap restoredThat 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.
update-mime resolves to what you intended to run.--local run produced a non-empty ~/.mailcap, or you know why no local handler applies.mailcap.order, never in generated output.