Format:Flatpak bundle
| Extensions | .flatpak, .flatpakref |
|---|---|
| License | LGPL-2.1 (flatpak) |
| On this wiki | Facts · Code · Notes · Topics |
A single-file .flatpak bundle is a GVariant of the OSTree static-delta superblock type (no magic number) whose metadata dictionary names the ref, origin, app metadata and optional GPG keys and icons; installed apps live in an OSTree repository with a deploy directory holding a metadata keyfile.
Two forms
- Repository: apps are pulled into an OSTree repository (objects store, content-addressed files) and checked out ("deployed") into a deploy directory that contains a
metadatakeyfile and thefiles/tree. flatpak-dir.c readsdeploy_dir/metadatain several places (for example line 3864). - Single-file bundle (
.flatpak): created for offline distribution. There is no file magic: flatpak_bundle_load (common/flatpak-repo-utils.c, lines 3681-3815) maps the whole file and callsg_variant_new_from_byteswith the typeOSTREE_STATIC_DELTA_SUPERBLOCK_FORMAT, i.e. the file is one serialized GVariant of OSTree's static delta superblock type.
Bundle layout as flatpak reads it
Child 3 of the superblock is the checksum of the target commit (32 bytes, to_csum_v, validated with ostree_validate_structureof_csum_v). Child 0 is a string-keyed dictionary (a{sv}) with these keys, all looked up in flatpak_bundle_load:
| Key | Type | Meaning |
|---|---|---|
ostree.endianness |
byte | l (little) or B (big): byte order of the GVariant data, swapped if it differs from the host
|
ref |
string | the full ref, for example app/org.example.App/x86_64/stable; required ("Invalid bundle, no ref in metadata")
|
origin |
string | URL of the originating repository |
runtime-repo |
string | repository to fetch the runtime from |
collection-id |
string | OSTree collection id (empty means none) |
metadata |
string | the application's metadata keyfile text
|
gpg-keys |
byte array | embedded GPG keys |
In common/flatpak-bundle-ref.c (lines 333-341) the dictionary also supplies appdata (AppStream, byte string), icon-64 and icon-128 (byte strings).
For the analyst
- Recognition is structural: a .flatpak is not ELF, not a tar, and has no magic bytes. Unverified: the GVariant type string is believed to be
(a{sv}tayay...); take the type from OSTree's source before parsing by hand. - Easiest route:
flatpak build-bundleoutput is read byostreetooling and by flatpak itself; Unverified:flatpak install --bundlefollowed by browsing the deploy directory under the flatpak data directory reachesfiles/bin. - The program binaries are ELF files under
files/(the app) and in separate runtime deployments (shared libraries). Unverified:files/as the root of the app tree.
See Technique:Identifying Linux and macOS package containers.
Sources
flatpak/flatpak (LGPL-2.1) at commit ed564f7cce: common/flatpak-repo-utils.c, common/flatpak-bundle-ref.c, common/flatpak-dir.c, read.
Code & repositories
- https://github.com/flatpak/flatpak @
ed564f7cce7e6f81926fc4a2d58125a4adf64649· license: LGPL-2.1-or-later (declared by the contributor; GitHub's detector did not recognize COPYING)
Flatpak: common/flatpak-repo-utils.c flatpak_bundle_load, flatpak-bundle-ref.c
Tested on: source read, not run · checked 2026-10-19