Flathub

https://docs.flathub.org
Admin
Flathub is a community-driven central repository where users discover, install, and keep Flatpak...
Tokens:35,364
Snippets:668
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install License Files with Post-Install Hook

Source: https://docs.flathub.org/docs/for-app-authors/requirements

Use the 'post-install' hook to move license files if they are not automatically installed. This example assumes licenses are in a 'LICENSES' subdirectory.

```yaml
- name: my-module 
  buildsystem: cmake-ninja 
  builddir: true 
  post-install: 
    - mkdir -p $FLATPAK_DEST/share/licenses/$FLATPAK_ID/<my-module-name> 
    - mv ../LICENSES/* $FLATPAK_DEST/share/licenses/$FLATPAK_ID/<my-module-name> 

```

--------------------------------

### Install Flatpak System-Wide

Source: https://docs.flathub.org/docs/for-users/user-vs-system-install

Use this command to install an application or runtime for all users on the system. This requires administrator privileges and installs to the system's Flatpak directory.

```bash
flatpak install <remote> <name>  
```

--------------------------------

### Install org.flatpak.Builder

Source: https://docs.flathub.org/docs/for-app-authors/submission

Installs the org.flatpak.Builder tool, which is recommended for building applications locally.

```bash
flatpak install -y flathub org.flatpak.Builder  
```

--------------------------------

### Install Runtime and SDK

Source: https://docs.flathub.org/docs/for-users/rebuilding

Installs the required Flatpak runtime and SDK for the target application. Ensure these match the versions specified in the manifest.

```bash
flatpak --user install flathub org.kde.{Platform,Sdk}//6.9
```

--------------------------------

### Install Application from Beta Repository

Source: https://docs.flathub.org/docs/for-users/installation

Install applications from the Flathub Beta repository by specifying 'flathub-beta' as the remote. Replace <app-id> with the application's identifier.

```bash
flatpak install flathub-beta <app-id>
```

--------------------------------

### Build and Install Manifest with Builder

Source: https://docs.flathub.org/docs/for-app-authors/submission

Builds and installs your application locally using the provided manifest file with org.flatpak.Builder.

```bash
flatpak run --command=flathub-build org.flatpak.Builder --install <manifest>  
```

--------------------------------

### Install Flatpak Builder

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Install the `org.flatpak.Builder` package from Flathub to access the MetaInfo linter.

```bash
flatpak install -y flathub org.flatpak.Builder
```

--------------------------------

### Post-Installation Steps Note

Source: https://docs.flathub.org/docs/for-app-authors/requirements

If users need to perform additional steps after installation, mention or link to them in the Appstream description.

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

--------------------------------

### Install Flatpak Per-User

Source: https://docs.flathub.org/docs/for-users/user-vs-system-install

Use this command to install an application or runtime for the current user only. The installation will be located in the user's home directory.

```bash
flatpak install --user <remote> <name>  
```

--------------------------------

### Website Verification Token Example

Source: https://docs.flathub.org/docs/for-app-authors/verification

Place this uniquely generated token at `https://<domain>/.well-known/org.flathub.VerifiedApps.txt` to verify domain ownership. Multiple tokens for different apps can be included on separate lines. Lines starting with '#' are ignored.

```text
# com.example.App  
00000000-aaaa-0000-aaaa-000000000000  

# com.example.AnotherApp  
 aaaaaaaa-0000-aaaa-0000-aaaaaaaaaaaa  

```

--------------------------------

### Install and Inspect a Flatpak Runtime

Source: https://docs.flathub.org/docs/for-users/finding-sources

Install a specific Flatpak runtime and then view its manifest file. The manifest contains information about the sources used to build the Flatpak.

```bash
flatpak install flathub org.kde.Platform//6.9  

flatpak run --command=cat org.kde.Platform//6.9 /usr/manifest.json  
```

--------------------------------

### Install Flatpak Sources Extension

Source: https://docs.flathub.org/docs/for-users/rebuilding

Installs the sources extension for a specific Flatpak application. This is the first step to obtain the necessary source files for rebuilding.

```bash
flatpak install --user flathub org.kde.minuet.Sources//stable
```

--------------------------------

### Install Latest Flatpak Version

Source: https://docs.flathub.org/docs/for-users/rebuilding

Installs the latest version of a Flatpak application from Flathub for user installation. This is a prerequisite for inspecting its build details.

```bash
flatpak --user install flathub org.kde.minuet
```

--------------------------------

### Project License Example

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

The `<project_license>` tag declares the application's software license. Use valid SPDX identifiers or expressions.

```xml
<project_license>GPL-3.0-only</project_license>
```

--------------------------------

### Start Flatpak Bisect Process

Source: https://docs.flathub.org/docs/for-users/bisecting

Initiates the bisecting process for a given application. This should be run first to set up the bisect session.

```bash
flatpak-bisect org.gnome.gedit start
```

--------------------------------

### Get Flatpak Commit Information

Source: https://docs.flathub.org/docs/for-users/finding-sources

Use the `flatpak info` command to retrieve detailed information about an installed Flatpak, including its commit hash and build subject, which can help trace its origin.

```bash
flatpak info flathub org.kde.Platform//6.9  
```

--------------------------------

### Install License Files Manually

Source: https://docs.flathub.org/docs/for-app-authors/requirements

Use this command within 'build-commands' if license files are not automatically installed. Ensure the LICENSE file is in the source root and specify the target directory.

```yaml
- name: my-module 
  buildsystem: simple 
  build-commands: 
    - install -Dm0644 LICENSE -t $FLATPAK_DEST/share/licenses/$FLATPAK_ID/<my-module-name> 

```

--------------------------------

### Example Flatpak Manifest Structure

Source: https://docs.flathub.org/docs/for-users/finding-sources

This is an excerpt of a Flatpak manifest file. It details the runtime, SDK, build options, and modules with their respective sources and build commands.

```json
{
  "id" : "org.kde.Sdk",
  "id-platform" : "org.kde.Platform",
  "branch" : "6.9",
  "runtime" : "org.freedesktop.Platform",
  "runtime-version" : "24.08",
  "runtime-commit" : "a993292d6ff150598dad4cd1f725aeee01a668b9e721b559ea1b6f6240174d58",
  "sdk" : "org.freedesktop.Sdk",
  "sdk-commit" : "880e38dedfd737008ddd0ebbbd0daaaed26b0d20011b0ce622d411a36446d607",
  "build-options" : {
    "env" : {
      "CMAKE_BUILD_TYPE" : "RelWithDebInfo"
    }
  },
  "modules" : [
    {
      "name" : "licence-extractor",
      "buildsystem" : "simple",
      "sources" : [
        {
          "commands" : [
            "DESTINATION=/usr/share/licenses/org.kde.Platform/$(basename `pwd`)/",
            "DESTINATION=${DESTINATION%-[0-9]*} ",
            "mkdir -p $DESTINATION",
            "cp -v ${LICENSES:-LICENSES/*} $DESTINATION"
          ],
          "dest-filename" : "install-licenses.sh",
          "type" : "script"
        }
      ],
      "build-commands" : [
        "install -m755 install-licenses.sh /usr/bin"
      ]
    },
    {
      "name" : "qt6-qtbase",
      "buildsystem" : "cmake-ninja",
      "config-opts" : [
        "-DINSTALL_ARCHDATADIR=lib",
        "-DQT_DISABLE_RPATH=ON",
        "-DBUILD_WITH_PCH=FALSE",
        "-DQT_FEATURE_openssl_linked=ON",
        "-DQT_FEATURE_system_sqlite=ON"
      ],
      "sources" : [
        {
          "url" : "https://download.qt.io/official_releases/qt/6.9/6.9.3/submodules/qtbase-everywhere-src-6.9.3.tar.xz",
          "sha256" : "c5a1a2f660356ec081febfa782998ae5ddbc5925117e64f50e4be9cd45b8dc6e",
          "x-checker-data" : {
            "type" : "anitya",
            "project-id" : 7927,
            "stable-only" : true,
            "versions" : {
              "<" : "6.10.0"
            },
            "url-template" : "https://download.qt.io/official_releases/qt/6.9/$version/submodules/qtbase-everywhere-src-$version.tar.xz"
          },
          "type" : "archive"
        },
        {
          "paths" : [
            "patch/qtbase-find_package-paths.patch"
          ],
          "type" : "patch"
        },
        {
          "commands" : [
            "install-licenses.sh"
          ],
          "type" : "shell"
        }
      ]
    }
  ]
}
```

--------------------------------

### Metadata License Example

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Specify the license for the MetaInfo file itself using the `<metadata_license>` tag. CC0-1.0 is recommended if upstream has not provided metadata.

```xml
<metadata_license>CC0-1.0</metadata_license>
```

--------------------------------

### Build Manifest with Builder (Extra Data)

Source: https://docs.flathub.org/docs/for-app-authors/submission

Builds your application manifest using org.flatpak.Builder, typically when using extra-data. Also installs the repository.

```bash
flatpak run --command=flathub-build org.flatpak.Builder <manifest>  
flatpak install --user -y ./repo $FLATPAK_ID  
```

--------------------------------

### Run Application with Specific Branch

Source: https://docs.flathub.org/docs/for-users/installation

Switch between 'beta' and 'stable' branches of an installed application using this command. This allows you to test different versions of the same application.

```bash
flatpak run --branch=<beta|stable> <app-id>
```

--------------------------------

### Application ID Example

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

The `<id>` tag must exactly match the application's ID in the Flatpak manifest. Avoid adding suffixes like `.desktop`.

```xml
<id>org.flatpak.qtdemo</id>
```

--------------------------------

### List Files in Flatpak Source Directory

Source: https://docs.flathub.org/docs/for-users/rebuilding

Displays the directory structure of the installed Flatpak sources extension, showing downloaded archives and manifest files. This helps in locating the required files for the build process.

```bash
tree ~/.local/share/flatpak/runtime/org.kde.minuet.Sources/x86_64/stable/fdafb56a6e907f87a359c8a048471fc1747291bdcbe0e952ad2d0cf3d66fc0dc/files
```

--------------------------------

### Select Specific Ref for Uninstallation

Source: https://docs.flathub.org/docs/for-users/uninstallation

When multiple versions or installations of an application exist, this command allows you to select a specific reference (ref) and location for uninstallation. Type the corresponding number to choose.

```bash
$ flatpak uninstall org.example.foo  

  
Similar installed refs found for ‘org.example.foo’:  

  
   1) app/org.example.foo/x86_64/stable (system)  

   2) app/org.example.foo/x86_64/beta (system)  

   3) app/org.example.foo/x86_64/beta (user)  

   4) All of the above  

  
Which do you want to use (0 to abort)? [0-4]:  
```

--------------------------------

### Git Module URL Configuration

Source: https://docs.flathub.org/docs/for-app-authors/linter

This example shows the correct configuration for a git module's URL in a Flatpak manifest. The 'url' property must point to a valid HTTP or HTTPS resource.

```yaml
module-module_name-source-git-no-url:
  type: git
  url: <url>
```

```yaml
module-module_name-source-git-url-not-http:
  type: git
  url: <url>
```

--------------------------------

### Example Flatpak Info Output

Source: https://docs.flathub.org/docs/for-users/finding-sources

This output from `flatpak info` shows key details about the Flatpak, such as its ID, branch, commit hash, and the subject line of the commit, which often contains a Git commit reference.

```text
KDE Application Platform - Shared libraries used by KDE applications  

        ID: org.kde.Platform  
       Ref: runtime/org.kde.Platform/x86_64/6.9  
      Arch: x86_64  
    Branch: 6.9  
   License: GPL-2.0+  
Collection: org.flathub.Stable  
  Download: 393,0 MB  
 Installed: 1,0 GB  

    Commit: 76413ad56178752c98dbda74682640d85a2b10b0d37f6f3680b29adf00265a6b  
    Parent: 12d7f68172eb7bf16d7853e37b17d035efbe82e8d42eb658a05483632bb7a27a  
   Subject: build of org.kde.Sdk, Wed Oct 15 12:57:40 PM UTC 2025, 094cc415694670dd34c808a48e500a73d1b177bb  
      Date: 2025-10-16 08:30:37 +0000  
```

--------------------------------

### Run Application Locally

Source: https://docs.flathub.org/docs/for-app-authors/submission

Runs your installed Flatpak application using its application ID.

```bash
flatpak run <app id>  
```

--------------------------------

### Git Module Branch Configuration

Source: https://docs.flathub.org/docs/for-app-authors/linter

This example demonstrates the correct way to configure a git module in a Flatpak manifest. It specifies using 'commit' or 'tag' instead of 'branch' for reproducibility.

```yaml
module-module_name-source-git-branch:
  type: git
  branch: <branch_name>
  commit: <commit_hash>
```

--------------------------------

### Uninstall Unused Dependencies

Source: https://docs.flathub.org/docs/for-users/uninstallation

After uninstalling applications, run this command to remove any leftover runtimes that are no longer needed by any installed application.

```bash
flatpak uninstall --unused
```

--------------------------------

### Check System Compatibility

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Use the `appstreamcli check-syscompat` command to get an overview of an application's system compatibility based on its metainfo XML file.

```bash
appstreamcli check-syscompat --details $FLATPAK_ID.metainfo.xml
```

--------------------------------

### View Application History

Source: https://docs.flathub.org/docs/for-users/downgrading

Use this command to view the commit history of an installed application, which is necessary to find the commit hash of the version you want to downgrade to.

```bash
flatpak remote-info --log flathub com.github.tchx84.Flatseal
```

--------------------------------

### Checkout First Known Good Commit

Source: https://docs.flathub.org/docs/for-users/bisecting

Checks out a specific commit identified from the build history. This commit serves as the starting point for identifying the regression.

```bash
flatpak-bisect org.gnome.gedit checkout 5cd2b0648618c9038fbc6830733817309ade29541cdd8383830bbb76f6accf0d
```

--------------------------------

### Prepare Build Directory and Copy Sources

Source: https://docs.flathub.org/docs/for-users/rebuilding

Creates a `.flatpak-builder` directory and copies the downloaded source archives into it. This prepares the local environment for the build process.

```bash
mkdir -p .flatpak-builder
cp -a ~/.local/share/flatpak/runtime/org.kde.minuet.Sources/x86_64/stable/fdafb56a6e907f87a359c8a048471fc1747291bdcbe0e952ad2d0cf3d66fc0dc/files/downloads .flatpak-builder
```

--------------------------------

### Get Flatpak Application Information

Source: https://docs.flathub.org/docs/for-users/rebuilding

Retrieves detailed information about an installed Flatpak application, including its commit hash, parent commit, and installation details. This information is crucial for identifying the exact version and sources to use.

```bash
flatpak info --user org.kde.minuet.Sources
```

--------------------------------

### Get Flatpak Build Commit Information

Source: https://docs.flathub.org/docs/for-users/rebuilding

Retrieves detailed information about an installed Flatpak, including the Git commit hash used for its build. This commit ID is crucial for identifying the exact version of the application.

```bash
flatpak info --user org.kde.minuet//stable
```

--------------------------------

### Update Flatpak Per-User

Source: https://docs.flathub.org/docs/for-users/user-vs-system-install

Use this command to update an application or runtime that was installed per-user. This command only affects installations for the current user.

```bash
flatpak update --user <name>  
```

--------------------------------

### Add Flathub Beta Repository

Source: https://docs.flathub.org/docs/for-users/installation

Use this command to add the Flathub Beta repository, which hosts alpha and beta versions of applications. Proceed with caution as these versions may be unstable.

```bash
flatpak remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo
```

--------------------------------

### Force Remove a Remote Repository

Source: https://docs.flathub.org/docs/for-users/uninstallation

Use this command to remove a remote repository without uninstalling any applications or runtimes that are currently installed from it. This is useful if you want to keep the installed software but no longer want to receive updates from that specific remote.

```bash
flatpak remote-delete --force <remote-name>
```

--------------------------------

### Downgrade Application to Specific Commit

Source: https://docs.flathub.org/docs/for-users/downgrading

Execute this command to downgrade an application to a specific version identified by its commit hash. Note that `sudo` is required for system-wide installations as downgrades are considered privileged actions. For per-user installations, run this command as the user.

```bash
sudo flatpak update \
      --commit=627f4091cfc8c6af3d51034c388c6bf7bcea341399ca49ca2b28590aee60a6c1 \
      com.github.tchx84.Flatseal
```

--------------------------------

### Add Flathub Repository

Source: https://docs.flathub.org/docs/for-app-authors/submission

Adds the Flathub repository to your system if it's not already present. This is necessary for installing Flatpak applications and tools.

```bash
flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo  
```

--------------------------------

### Create New Version Branch and Merge PR

Source: https://docs.flathub.org/docs/for-app-authors/maintenance

To prepare for a new version, create a new branch (e.g., 'branch/25.08') from the previous version's branch (e.g., 'branch/24.08'), then merge your PR branch into it.

```bash
git checkout -b branch/25.08 branch/24.08
git merge my-pr-branch
```

--------------------------------

### Remove a Remote Repository

Source: https://docs.flathub.org/docs/for-users/uninstallation

To delete a remote repository, use this command. If applications or runtimes are still installed from this remote, you will be prompted to remove them as well.

```bash
flatpak remote-delete <remote-name>
```

--------------------------------

### Name and Summary Tags

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Provide the application's name and a short summary. Ensure the name does not violate trademarks.

```xml
<name>App Name</name>
<summary>Short summary</summary>
```

--------------------------------

### Update Flatpak System-Wide

Source: https://docs.flathub.org/docs/for-users/user-vs-system-install

Use this command to update an application or runtime installed system-wide. This command affects all users and requires administrator privileges.

```bash
flatpak update <name>  
```

--------------------------------

### Create Beta Branch and Merge PR

Source: https://docs.flathub.org/docs/for-app-authors/maintenance

Use this command to create a 'beta' branch from 'master' and then merge your pull request branch into it. This is typically done after a successful build.

```bash
git checkout -b beta master
git merge my-pr-branch
```

--------------------------------

### Declare App Supports Desktop and Touch Devices

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Use the `<supports>` tag with child `<control>` elements to indicate that an app functions on both desktop and touch-enabled devices.

```xml
<!-- Desktop AND mobile supported -->
<supports>
  <control>keyboard</control>
  <control>pointing</control>
  <control>touch</control>
</supports>
```

--------------------------------

### Run Manifest Check with Flatpak Builder Lint

Source: https://docs.flathub.org/docs/for-app-authors/linter

Execute the manifest check using flatpak-builder-lint. This command analyzes your Flatpak manifest file.

```bash
flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest <manifest>
```

--------------------------------

### Add Flathub Verified Remote

Source: https://docs.flathub.org/docs/for-users/verification

Use this command to add only verified apps from Flathub to your local repository. This ensures you only install applications maintained or approved by their developers.

```bash
flatpak remote-add --if-not-exists --subset=verified --title='Flathub Verified' flathub-verified https://dl.flathub.org/repo/flathub.flatpakrepo  
```

--------------------------------

### Provide Application URLs

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Include various URLs for your application, such as homepage, bug tracker, and donation links. The 'homepage' URL is mandatory for validation.

```xml
<url type="bugtracker">https://example.org/issues</url>
<url type="homepage">https://example.org/</url>
<url type="donation">https://example.org/donate</url>
<url type="contact">https://example.org/contact</url>
<url type="faq">https://example.org/faq</url>
<url type="translate">https://example.org/translate</url>
<url type="contribute">https://example.org/contribute</url>
<url type="vcs-browser">https://example.org/repository</url>
```

--------------------------------

### Basic MetaInfo XML Structure

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

All MetaInfo files must begin with an XML declaration and a root `<component>` tag. The `type` attribute specifies the application category.

```xml
<?xml version="1.0" encoding="UTF-8"?>

<!-- Copyright [year] [name] -->  

<component type="desktop-application">

```

--------------------------------

### Custom Project License

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Use `LicenseRef-<identifier>` for custom licenses, where `<identifier>` is a valid license identifier.

```xml
<project_license>LicenseRef-<identifier></project_license>
```

--------------------------------

### Specify Translation File Prefixes

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

For applications using gettext or Qt translation files, specify the prefix with the `<translation/>` tag. This helps software centers identify available translations.

```xml
<translation type="gettext">gnome-builder</translation>
<translation type="qt">qtdemo</translation>
```

--------------------------------

### Override Flatpak Permission

Source: https://docs.flathub.org/docs/for-users/permissions

Modify a specific permission for a Flatpak application using the `flatpak override` command. This example removes the `--socket=pcsc` permission for Firefox.

```bash
flatpak override --user --nosocket=pcsc org.mozilla.firefox
```

--------------------------------

### Remote Icon

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

If console applications do not install an icon, use the icon tag with type set to 'remote'. The value must be a direct HTTP(S) URL to the icon file.

```xml
<icon type="remote">https://example.org/icon.png</icon>
```

--------------------------------

### Mark Current Commit as Bad

Source: https://docs.flathub.org/docs/for-users/bisecting

After starting the bisect process, mark the current commit as the first known 'bad' commit. This establishes the upper bound for the regression search.

```bash
flatpak-bisect org.gnome.gedit bad
```

--------------------------------

### Lint Repository

Source: https://docs.flathub.org/docs/for-app-authors/submission

Runs the flatpak-builder-lint tool on your repository to check for issues.

```bash
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo  
```

--------------------------------

### Run Repository Check with Flatpak Builder Lint

Source: https://docs.flathub.org/docs/for-app-authors/linter

Perform a repository check with flatpak-builder-lint. This requires an OSTree repository in the current path, typically generated with Flatpak Builder.

```bash
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo
```

--------------------------------

### Extract Flatpak Manifest

Source: https://docs.flathub.org/docs/for-users/rebuilding

Extracts the processed manifest file from an installed Flatpak. This manifest contains essential build information, including runtime and SDK commits, and source URLs.

```bash
flatpak run --user --command=/bin/cat org.kde.minuet /app/manifest.json
```

--------------------------------

### Define Application Releases

Source: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Provide release information including version, date, and details URL. The description can include HTML for formatting release notes.

```xml
<releases>
  <release version="1.0.1" date="2024-01-18">
    <url type="details">https://example.org/changelog.html#version_1.0.1</url>
    <description>
      <p>Release description</p>
        <ul>
          <li>List of changes</li>
          <li>List of changes</li>
        </ul>
    </description>
  </release>
  <release version="1.0.0" date="2023-08-07">
    <url type="details">https://example.org/changelog.html#version_1.0.0</url>
    <description>
      <p>Release description</p>
        <ul>
          <li>List of changes</li>
          <li>List of changes</li>
        </ul>
    </description>
  </release>
</releases>
```
Tokens:
Raw