Rebuild the Shared MIME Cache with update-mime-database

A new MIME type sits ignored until update-mime-database rebuilds the shared cache. This guide shows which 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 files can vary on another release, so check the local command on a different system.

• A shell and a MIME directory containing a packages subdirectory.
• Elevated privileges for a system-wide rebuild; reading the help and checking files does not need them.

Allow about ten minutes.

1. Check the installed command

Start with the executable, package version and help text, all 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

It takes one positional argument: the MIME directory itself, not the packages subdirectory 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 whichever directory actually holds the package files you changed.

2. Check the source directory before changing the cache

Inspect the target and its package files before rebuilding, substituting a different directory if yours differs:

$ 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, combines the MIME definitions, and writes the derived cache into the parent directory.

3. Rebuild the cache

After installing, removing or editing a MIME package, run the updater against the parent directory, using elevated privileges only for this one write:

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

A successful run normally returns to the prompt with no summary; the cache files are regenerated in place. On a user-owned directory, drop sudo:

$ update-mime-database "$MIME_DIR"

This is not a service restart and it does not install a MIME package. Applications that already loaded MIME data may need restarting before they see the new cache.

4. Use conditional mode in package scripts

Pass -n when a script should only rebuild 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-install and post-removal scripts, skipping unnecessary work when nothing under packages has changed since the version marker. It is a timestamp check, not a content comparison: a copied file can carry an older timestamp despite different contents, and a merely touched file can trigger a rebuild with no meaningful content change at all.

For a deliberate repair or a manually edited package XML, leave -n out and request a normal rebuild instead of relying on timestamps.

5. Verify the result

Check the exit status first; zero means it completed:

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

Then confirm the expected generated files exist with 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 depends on the installed release and source data; the local 2.4 build also writes XMLnamespaces, generic-icons, icons, types and treemagic. Treat the exit status as the primary 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 entry counts are release-specific, so do not build monitoring rules around their exact wording.

Common traps

• Wrong level. Pass /usr/share/mime, not /usr/share/mime/packages.
• Wrong account. Use sudo only when the target is not writable by your account; it will not repair invalid XML or create a missing package definition.
• Stale application state. A running desktop application may have cached MIME data of its own. Restart it before deciding the user-facing change is missing.
• Conditional surprise. -n can legitimately do nothing when timestamps say the cache is current. Drop it when you need a guaranteed rebuild.
• Unrelated XDG paths. A custom MIME directory is not automatically searched by applications. Make sure it sits under the data paths the target account and desktop environment actually use.