flatpak

Single-file Flatpak bundles

Currently electron-builder does not support publishing apps to Flatpak repositories like Flathub. Flatpak support in electron-builder is limited to generating single-file bundles which have limitations compared to apps installed from a repository.

The top-level flatpak key contains a set of options instructing electron-builder on how it should build a Flatpak bundle.

What is Flatpak?

Flatpak is a universal Linux packaging system that runs apps in a sandbox with controlled access to system resources. Unlike AppImage (no sandbox) and Snap (Ubuntu-primary), Flatpak is designed to be distro-agnostic and runs on any Linux distribution with flatpak installed.

Key characteristics:

• Sandboxed — apps run in an isolated environment with portal-based access to system resources
• Cross-distro — works on Ubuntu, Fedora, Arch, Debian, and more
• Runtime-based — apps are built against a specific runtime (freedesktop, GNOME, KDE)
• Distributed via Flathub (for repository-based distribution — note: currently not supported by electron-builder)

Flatpak vs. AppImage vs. Snap

Aspect	Flatpak	AppImage	Snap
Sandboxed	Yes (portals)	No	Yes (interfaces)
Distro support	Any (flatpak required)	Universal	Any (snapd required)
Store/repo	Flathub (not via eb)	N/A	Snap Store
Auto-update	Flathub (not via eb)	AppImageUpdate	Snap Store
electron-builder output	Single-file bundle	Single file	Package

Build Requirements

Install flatpak and flatpak-builder on your Linux build machine — see Flatpak setup.

Runtime and SDK

Flatpak apps run against a runtime that provides base libraries. Choose the runtime that matches your app's dependencies:

flatpak:
  runtime: org.freedesktop.Platform         # freedesktop (most common for Electron)
  sdk: org.freedesktop.Sdk
  runtimeVersion: "24.08"                   # runtime version

Common runtimes for Electron apps:

Runtime	SDK	Use Case
org.freedesktop.Platform	org.freedesktop.Sdk	Standard Electron apps (recommended)
org.gnome.Platform	org.gnome.Sdk	GNOME-integrated apps
org.kde.Platform	org.kde.Sdk	KDE-integrated apps

Install the runtime on your build machine before building — see available Flatpak runtimes.

Finish Args (Permissions)

The finishArgs array defines what the sandboxed app is allowed to access. Electron apps need several permissions:

flatpak:
  finishArgs:
    # Display
    - "--socket=x11"
    - "--socket=wayland"
    - "--share=ipc"              # shared memory with X11 compositor
    # Network
    - "--share=network"
    # Filesystem
    - "--filesystem=home"        # access user home directory
    # Desktop integration
    - "--talk-name=org.freedesktop.Notifications"
    - "--talk-name=org.kde.StatusNotifierWatcher"
    - "--talk-name=com.canonical.AppMenu.Registrar"
    # Electron-specific
    - "--device=dri"             # GPU access
    - "--socket=pulseaudio"      # audio

Common finish args for Electron:

Arg	Purpose
--socket=x11	X11 display
--socket=wayland	Wayland display
--share=ipc	Shared memory (required for X11)
--share=network	Network access
--filesystem=home	Home directory access
--device=dri	GPU/DRM device (for WebGL, video decode)
--socket=pulseaudio	Audio output
--talk-name=org.freedesktop.Notifications	Desktop notifications
--filesystem=xdg-download	Downloads folder only (less than --filesystem=home)

Branch

flatpak:
  branch: stable    # Default: master/main

The branch name is embedded in the Flatpak bundle and visible to users.

Extra Modules

Include additional system libraries not in the runtime:

flatpak:
  modules:
    - name: zlib
      buildsystem: autotools
      sources:
        - type: archive
          url: https://www.zlib.net/zlib-1.3.tar.gz
          sha256: "..."

Custom Files and Symlinks

Copy additional files into the app bundle:

flatpak:
  files:
    - - build/extra-binary        # source
      - /app/bin/extra-binary     # destination (absolute within Flatpak)
  symlinks:
    - - /app/bin/myapp            # target
      - /app/bin/myapp-alias      # symlink location

Wayland Support

flatpak:
  useWaylandFlags: true   # Appends --enable-features=UseOzonePlatform --ozone-platform=wayland when running under a Wayland session

Local Testing

Build and install the Flatpak locally:

electron-builder --linux flatpak
# This produces a .flatpak bundle file

# Install it (no root required)
flatpak install --user dist/myapp-1.0.0.flatpak

# Run it
flatpak run com.mycompany.myapp

Troubleshooting

If the build fails, enable debug logging to see the underlying flatpak-builder output:

env DEBUG="@malept/flatpak-bundler" electron-builder build --linux flatpak

Missing runtime: Install the runtime before building — see the Runtime section above.

Sandbox permission denied: Check the finishArgs — the app is likely trying to access something not in its allowed permissions. Run flatpak run --log-session-bus com.mycompany.myapp to see D-Bus access denials.

GPU rendering issues: Ensure --device=dri is in finishArgs for WebGL support.

Configuration

Interface: FlatpakOptions

Extends

• CommonLinuxOptions.TargetSpecificOptions

Properties

artifactName?

readonly optional artifactName?: string | null

The artifact file name template.

Inherited from

TargetSpecificOptions.artifactName

---

base?

readonly optional base?: string

Start with the files from the specified application. This can be used to create applications that extend another application. Defaults to org.electronjs.Electron2.BaseApp.

See flatpak manifest documentation.

---

baseVersion?

readonly optional baseVersion?: string

Use this specific version of the application specified in base. Defaults to 20.08.

See flatpak manifest documentation.

---

branch?

readonly optional branch?: string

The branch to use when exporting the application. Defaults to master.

See flatpak manifest documentation.

---

category?

readonly optional category?: string | null

The application category.

Inherited from

CommonLinuxOptions.category

---

description?

readonly optional description?: string | null

As description from application package.json, but allows you to specify different for Linux.

Inherited from

CommonLinuxOptions.description

---

desktop?

readonly optional desktop?: LinuxDesktopFile | null

The Desktop file

Inherited from

CommonLinuxOptions.desktop

---

executableArgs?

readonly optional executableArgs?: string[] | null

The executable parameters. Pass to executableName

Inherited from

CommonLinuxOptions.executableArgs

---

files?

readonly optional files?: [string, string][]

Files to copy directly into the app. Should be a list of [source, dest] tuples. Source should be a relative/absolute path to a file/directory to copy into the flatpak, and dest should be the path inside the app install prefix (e.g. /share/applications/).

See @malept/flatpak-bundler documentation.

---

finishArgs?

readonly optional finishArgs?: string[]

An array of arguments passed to the flatpak build-finish command. Defaults to:

[
  // Wayland/X11 Rendering
  "--socket=wayland",
  "--socket=x11",
  "--share=ipc",
  // Open GL
  "--device=dri",
  // Audio output
  "--socket=pulseaudio",
  // Read/write home directory access
  "--filesystem=home",
  // Allow communication with network
  "--share=network",
  // System notifications with libnotify
  "--talk-name=org.freedesktop.Notifications",
]

See flatpak manifest documentation.

---

license?

readonly optional license?: string | null

The path to EULA license file. Defaults to license.txt or eula.txt (or uppercase variants). Only plain text is supported.

---

mimeTypes?

readonly optional mimeTypes?: string[] | null

The mime types in addition to specified in the file associations. Use it if you don't want to register a new mime type, but reuse existing.

Inherited from

CommonLinuxOptions.mimeTypes

---

modules?

readonly optional modules?: any[]

An array of objects specifying the modules to be built in order.

See flatpak manifest documentation.

---

publish?

optional publish?: Publish

Inherited from

TargetSpecificOptions.publish

---

runtime?

readonly optional runtime?: string

The name of the runtime that the application uses. Defaults to org.freedesktop.Platform.

See flatpak manifest documentation.

---

runtimeVersion?

readonly optional runtimeVersion?: string

The version of the runtime that the application uses. Defaults to 20.08.

See flatpak manifest documentation.

---

sdk?

readonly optional sdk?: string

The name of the development runtime that the application builds with. Defaults to org.freedesktop.Sdk.

See flatpak manifest documentation.

---

symlinks?

readonly optional symlinks?: [string, string][]

Symlinks to create in the app files. Should be a list of [target, location] symlink tuples. Target can be either a relative or absolute path inside the app install prefix, and location should be a absolute path inside the prefix to create the symlink at.

See @malept/flatpak-bundler documentation.

---

synopsis?

readonly optional synopsis?: string | null

The short description.

Inherited from

CommonLinuxOptions.synopsis

---

useWaylandFlags?

readonly optional useWaylandFlags?: boolean

Whether to enable the Wayland specific flags (--enable-features=UseOzonePlatform --ozone-platform=wayland) in the wrapper script. These flags are only available starting with Electron version 12. Defaults to false.