var img = document.createElement('img'); img.src = "https://webstats.gnome.org//piwik.php?idsite=40&rec=1&url=https://docs.flathub.org/" + location.pathname; img.style = "border:0"; img.alt = "tracker"; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(img,s);
Skip to main content

Requirements

The goal of these requirements is to ensure that the applications hosted on Flathub are safe to use and integrate well in the desktop experience.

Inclusion policy​

tip

Each application is evaluated on a case-by-case basis and if you are unsure whether it fits the guidelines, please feel free to ask via GitHub issues or in the Flathub Matrix room.

Flathub aims to provide a curated collection of high-quality, sandboxed graphical desktop applications that seamlessly integrate with the Linux desktop environment and enhance the user experience.

This defines specific policies for submission and inclusion, and applies to all submissions that are (were) submitted or included after the policy was documented, for as long as they remain on Flathub. Submissions are accepted at the discretion of the reviewers and are liable to be removed even after they are included, if it is found to violate any policy. They must also comply with Flathub's Terms Of Service. These may evolve over time, and exceptions may be granted in specific cases.

tip

If you believe something is violating these policies, please open an issue.

Impermissible submissions​

Submissions must demonstrate sufficient functional scope, user-facing value, desktop integration and functionality and justify distribution.

The following non-exhaustive categories of submissions will not be accepted:

Non-functional submissions​

Submissions that are not fully functional or have easily visible issues at the time of submission.

Console software​

Console softwares will not be accepted. Exceptions may be given to Flatpak or Flathub related tooling.

Minimal submissions​

Submissions that offer very minimal functionality consisting of simple scripts, single or simple sources and/or exists as a thin wrapper or launcher around other tools will not be accepted.

Simple web wrapper applications that embed a web engine and load a remote website without adding significant functionality or meaningful desktop integration will not be accepted.

Exceptions can be given on a case by case basis.

Extensions​

Shell, window manager, desktop environment extensions will not be accepted.

Tray-only applications​

Applications that operate exclusively as tray applets will not be accepted.

System utilities​

System utilities which are generally used on host will not be accepted.

Environment-locked applications​

Applications that function only in highly specific environments such as requiring a particular desktop environment or distribution will not be accepted. Exceptions to this can be considered on a case by case basis. An example of an exception may be a desktop settings application.

Host-dependent applications​

Applications that rely on host components or complicated post installation setups for core functionality will not be accepted. Exceptions to this can be considered on a case by case basis.

Submissions incompatible or restricted by Flatpak sandbox​

Certain types of submissions, such as development tools, file managers, terminals, IDEs with a broad scope are generally not well-suited for Flatpak due to inherent sandboxing limitations and severely degrade the user experience. Unless these applications are being officially submitted by the upstream developers and/or upstream has explicitly committed to supporting Flatpak they will not be accepted. In some cases, submissions in these categories may not be accepted at all if the trade-offs outweigh the benefits of distributing them via Flatpak.

Duplicate submissions​

Multiple submissions of the same application (in terms of functionality, content, visuals, or user experience) each built with different frameworks or toolkits will not be accepted. Multiple submissions of a forked app with minimal changes in the fork (in terms of functionality, content, visuals, or user experience) will not be accepted.

Conflicting submissions​

If an application is provided by the upstream author or developers as a Flatpak outside of Flathub, third party submissions of it to Flathub will be rejected.

Software using emulation or translation layers​

Windows software submissions that are using Wine or any submissions that aren't native to the Linux desktop and is using some emulation or translation layer will only be accepted if they are submitted officially by upstream with the intention of maintaining it in an official capacity.

End-of-life dependency policy​

Submissions using an end-of-life runtime, extension or baseapp will not be accepted.

Submissions that use high-risk, end-of-life software, such as OpenSSL 1.x, Python 2, or Qt5 WebKit, and request the network or any other invasive permissions will not be accepted.

Submissions where the main application is itself end-of-life will not be accepted unless the submitter can demonstrate their ability to maintain it for the foreseeable future and perform runtime upgrades.

Software design and distribution policy​

Applications that include insecure or harmful design choices, such as disabling or bypassing security mechanisms, using insecure cryptographic practices, exposing or accessing sensitive information, or shipping overly permissive configurations will not be accepted.

Submissions that employ unethical, manipulative, or exploitative design patterns will also be rejected. Applications promoting gambling or games of chance involving real-world money are not permitted.

Projects must demonstrate reasonable structure, organization, maintainability, and be distributed in a verifiable manner. Open source and source-available projects must follow established conventions of their respective ecosystem.

Extensions or BaseApps​

Flatpak extensions that add support for new languages, language specific tooling etc. or BaseApps will need a clear use case defined and prospective users to be accepted.

Trust and history​

Submission decisions may take a submitter's prior conduct into account.

A pattern of policy violations, uncooperative behaviour, multiple abandoned or poorly maintained apps, misleading practices, or failure to address security and compliance issues may result in rejection of current or new submissions.

Misleading, malicious or illegal submissions​

Submissions that impersonate, engage or encourage to engage in unlawful activities; provide false, misleading information and functionality; attempt to deceive or violate any laws, trademarks and copyrights; act in a malicious manner or contains malicious code will not be accepted. In most cases these are liable to be outright rejected or removed from the store.

Generative AI policy​

Submission pull requests must not be generated, opened, or automated using AI tools or agents. Please also do not request review from any AI tools in the submission PR. Automated Copilot reviews on GitHub can be disabled by the submitter by going here and changing Repository access to exclude the repo.

Submissions or changes where most of the code is written by or using AI without any meaningful human input, review, justification or moderation of the code are not allowed.

Submissions or changes having low-quality AI-generated or AI-assisted code are not allowed.

Submissions or changes containing copyrighted, license-incompatible, or ethically questionable code are not allowed.

These submissions can be rejected without any further review.

Repeatedly violating these policies may result in a permanent ban from future submissions and activities.

Application ID​

important

Please choose the ID carefully and don't hesitate to ask the reviewers for help as it will determine the type of verification method available, if any.

If it needs to be renamed at any point, the application needs to be resubmitted.

The application ID is a constant and unique identifier of the application consisting of the reverse-DNS format {tld}.{vendor}.{product}.

The components of the ID are the substrings obtained by splitting it at each dot ..

Demangling an ID or any of its component means removing any leading underscore (_) and converting any other underscore (_) to a dash (-).

The domain from the ID is determined by reversing its components and demangling them to form a FQDN, which is then matched against PSL. If a match is not found in PSL, all component except the last from the previous final form is taken as the domain.

The following rules must be followed when creating application IDs.

  • The ID must not exceed 255 characters and must have at least 3 components. Applications must not exceed 5 components.

  • Each component must contain only the characters [A-Z][a-z][0-9]_. A dash - is only allowed in the last component.

  • The domain portion must be in lowercase and must convert dash - to underscore _. If any component has an initial digit, it needs to be prefixed with an underscore similarly.

  • The ID must not end in generic terms like .desktop, .app, .linux. It's fine to repeat the application name in such cases.

  • The ID must exactly match the ID tag in Metainfo file.

  • Applications using code hosting IDs and hosted on github.com, gitlab.com, codeberg.org, framagit.org must use io.github., io.gitlab., page.codeberg., io.frama. prefixes respectively and must have at least 4 components.

    com.github., com.gitlab., org.codeberg., org.framagit. prefixes are reserved for official projects of the code hosting platform.

    Applications using code hosting IDs and hosted on Sourceforge can use io.sourceforge., net.sourceforge. prefixes.

Control over domain or repository​

  • The domain must be directly related to the project or the application being submitted and the author or the developer or the project must have control over the domain. The corresponding URL must be reachable over HTTPS. In some edge cases, if it is not reachable, an exception can be granted after manually checking.

    Verification may require placing a token under https://{domain name}/.well-known/org.flathub.VerifiedApps.txt

    It's preferable to have visible proof on the webpage linking the application or the developer or the project to the domain calculated from the ID.

Code hosting​

A repository URL (or project URL) is calculated for code hosting IDs by using the domain and by taking the last component of the ID as-is (except when the last component starts with a leading underscore and then a digit, in which case following Appstream conventions, the leading underscore is stripped from that component).

Note, that some code hosting platforms like GitLab may have case-sensitive namespaces.

  • Applications using code hosting IDs must have the repository URL reachable. In some cases, if the calculated code hosting URL doesn't match exactly, an exception can be granted after manually checking.

For example, the repository URL for the ID io.github.example_foo.bar will be https://github.com/example-foo/bar and for the ID io.sourceforge.example_foo.bar, it will be https://sourceforge.net/projects/example-foo/.

Protected ID prefixes​

Extensions and BaseApps​

BaseApps must have BaseApp as the last component of the Flatpak ID and for the rest of the ID, the above rules apply.

Flatpak extensions must prefix their ID with the extension point ID, which is either defined in one of the runtimes or in an app. If the extension point is defined in an app, it must use the app's ID as a prefix. They are exempt from the domain control rules.

Renaming Flatpak ID​

Flatpak IDs (app IDs) are supposed to be a constant and unique identifier throughout an app's lifetime. As such, app ID renames are conservatively accepted on a case-by-case basis provided valid reasons for the rename exists.

While exceptions can be made (for example an upstream ID change makes the currently published app non-functional), in general, the following types of renames won't be accepted.

  • A rename that does not change the domain portion of the app ID will not be accepted.

  • A rename changing the domain portion of the app ID but the previous app is already verified.

  • A rename that changes the domain portion of the app ID but with no intention to verify it will not be accepted.

License​

All content hosted on Flathub must allow legal redistribution, and the license must be correctly specified in the app's MetaInfo file.

Non-redistributable sources must use extra-data source type. Any part of the application such as the name or icon must not violate any trademarks and must be distinct.

License must be correctly declared in the metainfo file and must match with license information available in its source.

Installing license files​

Application maintainers and submitters must ensure that license files for each module in the Flatpak manifest is installed to $FLATPAK_DEST/share/licenses/$FLATPAK_ID.

Recent versions of Flatpak builder can do this automatically for common license file names as long as the module does not use buildsystem: simple, in which case the licence file must be manually installed.

  - name: my-module
    buildsystem: simple
    build-commands:
      - install -Dm0644 LICENSE -t ${FLATPAK_DEST}/share/licenses/$FLATPAK_ID/my-module

Permissions​

Static permissions must be kept to an absolute minimum. Applications should rely on XDG Portals and follow established XDG standards wherever possible.

When a suitable XDG portal exists, is supported across the ecosystem, and covers the application's use case, or can be implemented in the application itself — using the portal becomes mandatory instead of static permissions. Exceptions to this can be allowed on a case by case basis but note that using niche or unmaintained setups or dependencies may not count as grounds for allowing an exception.

No network access during build​

All dependencies needed to build and run the application must be present in the manifest as sources with publicly accessible URLs or must be included as local sources in the submission pull request. Binary or precompiled files must not be present in the submission pull request.

There is no network access during the build process. This means using --share=network inside build-args will not work.

# This will NOT work
build-options:
  build-args:
    - --share=network

Building from source​

All source available submissions must be built entirely from source code. This requirement applies to the main application component defined in the manifest, as well as any runtime dependencies included in the manifest.

Exceptions may be granted to well-known vendors on a case-by-case basis, for example where the necessary tooling to perform an offline source build is not available. However, the use of niche tooling or uncommon build setups may not constitute grounds for an exception.

When tooling for an offline source build is unavailable, application developers are generally encouraged (though not strictly required) to help develop, contribute, or upstream the necessary tooling for their app and for the benefit of the wider Flatpak ecosystem.

Patches​

Submissions must aim to distribute the application with minimal modifications and must closely follow the upstream source.

If any modifications are necessary (e.g., through patching), all patches must be included in the submission along with the manifest.

Stable releases​

The Flathub stable repository is dedicated to hosting only stable software. The Flathub beta repository can be used to publish beta software, though it will not be listed on the website and users must be manually migrated if switched to the stable repo later.

Nightly releases, development snapshots, or any software requiring daily updates must not be published to either repo.

Required files​

important

Under no circumstances should source code nor build artificats be included in the submission. Flathub is not intended to host neither application source code nor binaries, including that of any dependencies.

The following files must be included in the submission.

Manifest​

The application manifest must be at the top level and named after the application ID with the extension .json, .yml or .yaml depending on whether it is a JSON or YAML file.

The runtime(s) used in the manifest must be hosted on Flathub.

flathub.json​

Flathub builds on both x86_64 and aarch64 by default. If the application is supported on only one architecture, please include a flathub.json file in the submission pull request with the proper contents.

The flathub.json file must reside in the top-level root, next to the Flatpak manifest.

Dependency manifest​

There is no network access during the build process so all dependencies used by the application must be supplied in the specified in the manifest as sources with publicly accessible URLs so that they can be downloaded before the build starts.

There is a community provided set of tools that can be used to generate dependency manifests for npm, yarn, cargo, pip etc.

These manifests must be included in the submission.

Required metadata​

Applications must provide the following metadata typically as part of their source code.

important

These metadata files must be integrated in the upstream project. Please do not include a copy in the submission pull request unless it is using an extra-data source for the application.

Name and Icon​

No trademark violations​

The application name and icon as presented to the Flathub website and to users must be distinct and must not violate any trademarks.

Official affiliation must not be implied by using a vendor's name in the application name or icon unless the application is actually part of that vendor's project.

Icons must be sufficiently distinct to convey the project's own identity and prevent any risk of user confusion.

Some common examples of things to avoid include:

  • A Firefox fork cannot mention Firefox in its name or use any of the official icon, logo or artwork.
  • Third party apps, for example, a music player made for GNOME or COSMIC cannot use GNOME or COSMIC in its name or use any of the official icon, logo or artwork.
  • A WhatsApp client or wrapper cannot have WhatsApp in its name or use any of the official icon, logo or artwork.

Vendors often have their own requirements and policies. Some are listed below. Please refer to them for further details.

Appstream​

All submissions must provide a Metainfo file that passes validation.

A Metainfo file is mandatory to appear on the Flathub website.

Metainfo file is optional for runtimes, extensions and BaseApps.

Description notes​

Unofficially packaged, proprietary submissions must add a note like below as the first p tag of description.

Unofficially packaged, open source submissions may also follow this.

<description>
  <p>**This is a community package of APP NAME and not officially supported by UPSTREAM NAME.**</p>
</description>

If the submission is unavailable in English and only exists in a small number of select locales, a similar note must be added.

<description>
  <p>**This app is only available in LANG NAME.**</p>
</description>

If the user needs to perform additional post installation steps to run the submission, they must be mentioned or linked.

<description>
  <p>**Please follow https://example.org/setup after installation.**</p>
</description>

Desktop file​

All graphical applications must include a desktop file.

Icons​

Graphical applications must provide, preferably a SVG icon or at least a 256x256 PNG icon, properly named and installed.