Product SiteDocumentation Site

2.2. Desktop Applications

2.2.1. Introduction

A desktop application is an application which has a graphical user interface and is commonly used with mouse and keyboard. It also ships a Freedesktop .desktop file to be visible in application menus.
AppStream generators may pull data from the preexisting .desktop files to represent an application in the AppStream metadata pool. Upstream projects should ship a small XML file containing additional metadata to describe their application though, to enhance the available metadata. This data includes things like screenshots, long descriptions, icon information and various other things needed to present the application properly to the user. For some distributions, the presence of this metadata is a prerequisite for the application showing up in the metadata pool and being presented in software centers.
The file described in this document is built upon the generic component metadata with fields specific for desktop applications (see Section 2.1, “Generic Component”).
The metainfo files override any values which are automatically fetched from other sources by the AppStream data generator, which means that its data will always take precedence over data which has already been defined in a .desktop file. Applications can ship one or more files in /usr/share/metainfo/%{id}.appdata.xml.


If you are looking for some quickstart guide to just get your application to ship AppStream metadata quickly, this document might not be for you. You might want to take a look at Section 4.1, “For GUI application upstream maintainers” instead.

2.2.2. File specification

The basic structure for a generic component as described at Section 2.1.3, “XML Specification” applies. Note that the XML root must have the type property set to desktop, while in a generic component this property can be omitted. This clearly identifies this metainfo document as describing an application.


All tags defined in the generic component specification are valid for desktop application components as well. An application is just a specialized component, allowing tools like software centers to filter out the component types they want to display.
The following list describes the special tags for application upstream metadata and provides some additional information about the values the tags are expected to have. If no information is given about a tag, refer to the respective tag in Section 2.1, “Generic Component”.
For applications, the <id/> tag value must be the same name as the installed .desktop file for the application, the .desktop suffix of the filename may be omitted.
Usually, modern .desktop files follow the reverse-DNS scheme name already. If they do not follow the scheme, it is strongly recommended to change the .desktop filename. Refer to the desktop entry specification for more information.
Example: If your application's .desktop file is named org.example.FooBar.desktop the component-id must be org.example.FooBar (or org.example.FooBar.desktop). If your application's .desktop file is named frobnicator.desktop the component-id must be frobnicator (or frobnicator.desktop) - it is highly recommended to modernize the .desktop filename to follow the Desktop Entry specification in these cases though.
The <metadata_license/> tag as described in <metadata_license/> must be present.
While this tag is always requited for a generic component, for an application metainfo file it is not necessary, but only recommended. You can omit this tag if you want the software center to have the same strings as defined in the Name field of the .desktop file. In some cases it might be required to have a different name in the software center, but most metainfo files will not need this.
If no name tag and no Name field is present, the metadata is considered invalid and might be ignored by the AppStream generator.
While this tag is always requited for a generic component, for a desktop-application metainfo file it is only essential if the accompanying .desktop file does not have a Comment= field. If the metainfo file has a summary, it wil override the value found in the Comment field of the .desktop file.
If no summary tag and no Comment field is present, the metadata is considered invalid and might be ignored by the AppStream generator.
A screenshot presents your application to the outside world, and could be seen by hundreds or thousands of people.
The <screenshots/> tag should look like it is described at <screenshots/>.
Screenshot size, shape and format recommendations for applications:
  • All screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620px (software center applications will be able to fill in the screenshots in the space they provide for that more easily then).
    Ideally the window will be resized to a 16:9 aspect ratio, but screenshots can also be cropped if only a small area of the window needs to be shown.
  • Screenshots should be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other images where a lossy format like JPEG may compress better.
  • Do not scale screenshots below their original size.
You can find a lot more information on how to create good screenshots in the quickstart guide on applications.
This tag is described for generic components at Section 2.1.3, “XML Specification”. You should use it for your application if appropriate.
This tag is described in detail for generic components at <provides/>.
If your application ships a binary in a location in the default PATH, you should add at least a child of type <binary/> to make that new executable known to the distribution.
The application metainfo should at least provide one <releases/> tag, which has one or more <release/> childs to define the version and release date of this application. For details, see <releases/> .
For a component of type desktop-application, the following tags are required and must always be present: <id/>, <description/>, <metadata_license/>. The following tags are strongly recommended / required conditionally: <name/>, <summary/>.