Rebuild the Shared MIME Cache with update-mime-database

When a MIME package has been installed, removed or edited, you can rebuild the Shared MIME-Info cache with update-mime-database. This guide shows the directory to pass, the difference between a forced rebuild and the package-friendly conditional mode, and a small verification routine.

The examples use update-mime-database 2.4 from Debian package shared-mime-info 2.4-4, installed here as /usr/bin/update-mime-database. Option names and generated file details can vary with another release, so check the local command when maintaining a different system.

Allow about ten minutes. You need a shell and a MIME directory containing a packages subdirectory. Rebuilding a system-wide directory normally needs elevated privileges. Reading the command help and checking files does not.

1. Check the installed command

Start with the executable, package version and help text. These are ordinary read-only checks:

$ command -v update-mime-database
/usr/bin/update-mime-database
$ update-mime-database -v
update-mime-database (shared-mime-info) 2.4
$ update-mime-database -h
Usage: update-mime-database [-hvVn] MIME-DIR

The command takes one positional argument: the MIME directory, not the packages directory and not one XML file. The usual system-wide target is /usr/share/mime. A per-user database may live below your XDG data directory instead. Use the directory that actually contains the package files you changed.

2. Check the source directory before changing the cache

Inspect the target and its package files before rebuilding. Substitute a different directory if your installation uses one:

$ MIME_DIR=/usr/share/mime
$ test -d "$MIME_DIR/packages" && echo "packages directory exists"
packages directory exists
$ find "$MIME_DIR/packages" -maxdepth 1 -type f -name '*.xml' -printf '%f\n' | sort | sed -n '1,12p'

Each application or package normally contributes an XML file under packages. The updater scans those files, combines their MIME definitions, and writes the derived cache into the parent MIME directory. Do not edit mime.cache, globs2 or the other generated files by hand. Your durable change belongs in the package XML, followed by a rebuild.

3. Rebuild the cache

After installing, removing or modifying a MIME package, run the updater with the parent directory. For the system directory, use elevated privileges only for this write operation:

$ sudo update-mime-database /usr/share/mime

A successful run normally returns to the prompt without a summary. The cache files are regenerated in place. On a user-owned directory, omit sudo:

$ update-mime-database "$MIME_DIR"

The command is not a service restart and it does not install a MIME package. Applications that have already loaded MIME data may need to be restarted before they observe the new cache.

4. Use conditional mode in package scripts

Pass -n when a script should rebuild only if the source data is newer than the MIME directory's version file:

$ sudo update-mime-database -n /usr/share/mime

This is useful in package post-installation and post-removal scripts. It avoids unnecessary work when no file in packages has changed since the cache version marker. It is a timestamp check, not a content comparison: a copied file can have an older timestamp even when its contents differ, and a touched file can trigger a rebuild without a meaningful content change.

For a deliberate repair or a manually edited package XML, leave out -n. That requests a normal rebuild and avoids relying on timestamps.

5. Verify the result

First check the exit status. A zero status means the command completed successfully:

$ sudo update-mime-database /usr/share/mime
$ printf 'exit status: %s\n' "$?"
exit status: 0

Then confirm that the expected generated files exist and have a recent modification time:

$ for file in version mime.cache globs2 magic aliases subclasses; do
>     test -f "/usr/share/mime/$file" && printf '%s\n' "/usr/share/mime/$file"
> done
/usr/share/mime/version
/usr/share/mime/mime.cache
/usr/share/mime/globs2
/usr/share/mime/magic
/usr/share/mime/aliases
/usr/share/mime/subclasses

The exact set can depend on the installed release and source data. The local 2.4 build also writes files such as XMLnamespaces, generic-icons, icons, types and treemagic. Treat the exit status as the primary success check, and use file inspection to catch a wrong target directory.

For more detail while investigating, add -V:

$ update-mime-database -V /path/to/mime-directory
Updating MIME database in /path/to/mime-directory...
Wrote aliases ...

The verbose offsets and the number of entries are release-specific. Do not write monitoring rules that depend on their exact wording.

Common traps

• Wrong level: pass /usr/share/mime, not /usr/share/mime/packages.
• Wrong account: use sudo only when the target directory is not writable by the current user. It does not repair invalid XML or create a missing package definition.
• Stale application state: a running desktop application may have cached MIME information. Restart that application before declaring the user-facing change absent.
• Conditional surprise: -n can legitimately do nothing when timestamps say the cache is current. Omit it when you need a guaranteed rebuild.
• Unrelated XDG paths: a custom MIME directory is not automatically searched by applications. Make sure it is under the data paths used by the account and desktop environment that will consume it.