The [XDG Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) defines a standard for applications to integrate into application menus of [desktop environments](https://wiki.archlinux.org/title/Desktop_environment "Desktop environment") implementing the [XDG Desktop Menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html) specification. ## Validate Entry ```shell desktop-file-validate something.desktop ``` ## Update Entries ```shell update-desktop-database ``` Optionally, a target directory to process can be specified. ## Open Entry ```shell gio launch something.desktop ``` The [[gio]] tool does a lot of other things as well. This particular [feature](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1779) was added in 2020 while [other](https://gitlab.gnome.org/GNOME/glib/-/issues/54#note_976414) [[#Open in Editor|commands]] refuse to implement this functionality for ridiculous reasons. Possible alternatives: ```shell kioclient exec something.desktop exo-open something.desktop # may vary per distro ``` ## Other Commands ### Launch Installed ```shell gtk-launch appname ``` > Source file [gtk/gtk-launch.c](https://github.com/GNOME/gtk/blob/4724a89022ef1bec93b1a42d4cf2fec7191ed712/gtk/gtk-launch.c) shows that gtk-launch doesn't execute anything, but puts a message on D-Bus to to ask for the launch the required application. The `gtk-launch` command only works for `.desktop` file *already* available in the database. The `appname` is the filename with or without the extension. ### Open in Editor ```shell xdg-open something.desktop gnome-open something.desktop ``` These will open the file in a text editor, rather than open the program the `.desktop` file points to. # Locations While `.desktop` files can be placed anywhere to act similar to a shortcut, in order to get them integrated with your desktop environment there are specific places to put them. As long as the `.desktop` file is in one of the 4 locations below, MIME type associations should be automatically loaded by your desktop environment and file manager. ## Desktop To make an entry visible on the desktop, place the file in `~/Desktop/` directory. ## Menu To make an entry visible and searchable in a menu such as `budgie-panel`, there are a few different locations the file could be put: - User: `~/.local/share/applications/` - System-wide: `/usr/share/applications/` - Or: `/usr/local/share/applications/` # Tips ## Case Sensitivity I haven't tested this extensively, but when I used a capital letter at the start of a `.desktop` file, Budgie was able to display it in the menu but no longer able to launch it. `gtk-launch` also had this issue. May be related to the fact that a file with the same name but different case existed or a lag in database updates. Something to look out for though. ## Autonaming Some file managers, like Nemo, will synchronize the filename and the `Name` field for the current locale. For example, renaming `foo.desktop` on an English US system will also change the `Name[enUS]` field inside the file to match automatically. ## Actions https://askubuntu.com/questions/1127870/how-to-extend-a-desktop-file-for-adding-new-actions # Resources - [Arronax](https://www.florian-diesch.de/software/arronax/) visual desktop entry file editor - [Linux Desktop File support](https://marketplace.visualstudio.com/items?itemName=nico-castell.linux-desktop-file) for [[VS Code]] - https://github.com/faheel/desktop-entry-creator # References - https://help.gnome.org/admin//system-admin-guide/2.32/menustructure-desktopentry.html.en - https://wiki.archlinux.org/title/Desktop_entries - https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/ - https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html - https://amir.rachum.com/obsidian-uri-linux/ (for use with Obsidian) # Template ```toml #!/usr/bin/gio launch # The shebang line allows desktop files to be launched directly from the commandline. # So long as glib2's gio tool is installed. [Desktop Entry] # REQUIRED [String] The name of the application. Also, at least the current locale version of the name also needs to be listed in order for it to show up properly in file managers and on desktops. Name= Name[en_US]= # [String] A comment which can/will be used as a tooltip Comment= # [String/path] The path to the folder in which the executable is run Path= # [String/path] The executable of the application, possibly with arguments. Exec= # [String/path] The name of the icon that will be used to display this entry Icon= # [String/semicolon-delimited] Describes the categories in which this entry should be shown in a menu Categories= ############################### # DEFAULT FIELDS # ############################### # The version of the desktop entry specification to which this file complies Version=1.5 # REQUIRED [String] Specifies the type of item. This value is one of the following: # - Application: An item that starts an application. # - Link: An item that links to a file, folder, or a remote resource (such as a FTP site, a web page, a Windows share...). SEE ALSO: URL # - FSDevice: An item that is a file system device. # - Directory: An item that is a Directory. Type=Application # [Boolean] Describes whether this application needs to be run in a terminal or not Terminal=false ############################### # ADDITIONAL OPTIONAL FIELDS # ############################### # NOTE: The `Encoding` key is deprecated. # [String] A generic name of the application if helpful, like "Web Browser" for Firefox #GenericName= # [String/semicolon-delimited] A list of strings which may be used in addition to other metadata to describe this entry. This can be useful e.g. to facilitate searching through entries. The values are not meant for display, and should not be redundant with the values of Name or GenericName. #Keywords= # [Boolean] NoDisplay means "this application exists, but don't display it in the menus". This can be useful to e.g. associate this application with MIME types, so that it gets launched from a file manager (or other apps), without having a menu entry for it (there are tons of good reasons for this, including e.g. the netscape -remote, or kfmclient openURL kind of stuff). #NoDisplay= # [String/path] Path to an executable file on disk used to determine if the program is actually installed. If the path is not an absolute path, the file is looked up in the $PATH environment variable. If the file is not present or if it is not executable, the entry may be ignored (not be used in menus, for example). #TryExec= # [String/semicolon-delimited] The MIME type(s) supported by this application #MimeType= # [String] If entry is Link type, the URL to access. REQUIRED if Link type. #URL= # [Boolean] If true, the application has a single main window, and does not support having an additional one opened. This key is used to signal to the implementation to avoid offering a UI to launch another window of the app. This key is only a hint and support might not be present depending on the implementation. #SingleMainWindow= # [Boolean] If true, the application prefers to be run on a more powerful discrete GPU if available, which we describe as “a GPU other than the default one” in this spec to avoid the need to define what a discrete GPU is and in which cases it might be considered more powerful than the default GPU. This key is only a hint and support might not be present depending on the implementation. #PrefersNonDefaultGPU= ############################### # DOCUMENTATION # ############################### # https://specifications.freedesktop.org/desktop-entry-spec/latest/ # The value types recognized are string, localestring, boolean, and numeric. # - Values of type string may contain all ASCII characters except for control characters. # - Values of type localestring are user displayable, and are encoded in UTF-8. # - Values of type boolean must either be the string true or false. # - Values of type numeric must be a valid floating point number as recognized by the %f specifier for scanf in the C locale. ```