desktop-file-install

desktop-file-install [OPTION...] FILE...

--dir=DIRECTORY
    Specify the target directory for installation. Default is /usr/share/applications/ for system-wide or ~/.local/share/applications/ if run as a regular user.

--vendor=VENDORID
    Prefix the desktop file's ID with a vendor ID, e.g., 'kde-'.

--delete-original
    Delete the source .desktop file after a successful installation.

--set-name=NAME
    Set or override the application's name in the 'Name' field.

--set-icon=ICON
    Set or override the application's icon in the 'Icon' field. ICON refers to a name, not a path, e.g., 'firefox'.

--set-exec=COMMAND
    Set or override the command to execute when launching the application in the 'Exec' field.

--add-category=CATEGORY
    Add a category to the 'Categories' field, making the application appear in relevant menu sections.

--add-mime-type=MIMETYPE
    Add a MIME type association to the 'MimeType' field, allowing files of that type to be opened by this application.

--set-key=KEY=VALUE
    Set or override any arbitrary key-value pair within the desktop file. Use with caution.

--rebuild-database
    Force the rebuilding of the desktop file database after installation. This is generally recommended.

--no-rebuild-database
    Prevent the automatic rebuilding of the desktop file database.

--verbose
    Enable verbose output, showing more details about the installation process.

The desktop-file-install command is a utility for installing and updating .desktop files, which are configuration files used by Linux desktop environments (such as GNOME, KDE, XFCE) to describe applications. These files provide information necessary for launching applications, displaying them in menus, associating them with MIME types, and more.

This command automates the process of placing .desktop files into the correct directories, typically /usr/share/applications/ for system-wide installations or ~/.local/share/applications/ for user-specific installations. Beyond simple file copying, desktop-file-install ensures proper integration by updating system caches like the desktop file database (via update-desktop-database) and icon caches (via tools like gtk-update-icon-cache).

It also allows for on-the-fly modification of the .desktop file's attributes, such as setting the application name, icon, execution command, categories, or MIME types. This makes it a crucial tool for software installers and package managers to ensure applications are correctly registered and accessible within the desktop environment according to the FreeDesktop.org Desktop Entry Specification.

When using desktop-file-install, ensure the source .desktop file adheres to the FreeDesktop.org Desktop Entry Specification to avoid parsing errors or incorrect behavior.

Modifying existing system .desktop files directly without proper packaging might lead to issues during system updates. It's generally safer to install user-specific .desktop files in ~/.local/share/applications/ or use the package manager for system-wide changes.

While desktop-file-install often triggers database updates, issues with desktop menus or icons may still require manually running commands like update-desktop-database or gtk-update-icon-cache.

The primary purpose of desktop-file-install is to ensure that installed .desktop files comply with the FreeDesktop.org Desktop Entry Specification. This specification defines the structure and content of .desktop files, enabling desktop environments to correctly interpret and display application information, launch applications, and manage their associations with file types. Adhering to this standard is crucial for applications to integrate seamlessly into modern Linux desktops.

A key feature of desktop-file-install is its ability to automatically trigger updates to relevant system databases and caches. By default, it calls update-desktop-database to rebuild the cache of installed desktop files, ensuring that new applications appear in menus and launchers. It also typically triggers updates to icon caches (e.g., via gtk-update-icon-cache) so that application icons are correctly displayed. This automation significantly simplifies application installation for both users and package maintainers.

desktop-file-install is part of the xdg-utils project, which provides a set of tools that implement the FreeDesktop.org standards. The FreeDesktop.org initiative aims to promote interoperability and shared technologies across different Linux desktop environments like GNOME, KDE, and XFCE.

This command, along with others in xdg-utils, was developed to standardize common desktop tasks, such as managing application launchers, opening files with preferred applications, and installing fonts, ensuring a consistent user experience regardless of the underlying desktop environment. Its development reflects the ongoing effort to unify and improve the Linux desktop ecosystem.

update-desktop-database(1), xdg-desktop-menu(1), xdg-mime(1), gtk-update-icon-cache(1), update-mime-database(1)