Skip to content

Commit 5871bfa

Browse files
jasonrandrewsjasonrandrews
authored
Merge pull request #3135 from jasonrandrews/review2
Flatpak install guide
2 parents 6ca8e08 + 511d108 commit 5871bfa

1 file changed

Lines changed: 255 additions & 0 deletions

File tree

‎content/install-guides/flatpak.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
---
2+
title: "Flatpak"
3+
minutes_to_complete: 10
4+
official_docs: "https://flatpak.org"
5+
author: "Jason Andrews"
6+
description: "Install Flatpak on Arm Linux, add the Flathub remote, and verify the setup by running a native aarch64 application."
7+
weight: 1
8+
draft: true
9+
tool_install: true
10+
layout: installtoolsall
11+
multi_install: false
12+
multitool_install_part: false
13+
---
14+
15+
Flatpak is a framework for distributing Linux applications. It provides distribution-agnostic packaging and a sandboxed runtime, so the same application bundle runs on Ubuntu, Fedora, Arch, and openSUSE without repackaging. [Flathub](https://flathub.org/) is the primary community-maintained repository of Flatpak applications, many of which publish native Arm builds.
16+
17+
## How does Flatpak sandboxing work?
18+
19+
Each Flatpak application runs inside an isolated environment built on three Linux kernel features: namespaces, seccomp, and cgroups. Namespaces give the application its own view of the filesystem, network, and process tree. Seccomp filters restrict the system calls the application can make. Together, these mechanisms prevent an application from reading files outside its sandbox or interfering with other processes on the host.
20+
21+
The sandbox is implemented by [bubblewrap](https://github.com/containers/bubblewrap), a low-level sandboxing tool that Flatpak calls at launch time. Applications declare the permissions they need, such as access to the home directory, the network, or audio devices, in a manifest. You can inspect and override these permissions using `flatpak override`.
22+
23+
## How are Flatpak applications packaged?
24+
25+
A Flatpak application is distributed as an OSTree commit, a content-addressed filesystem tree stored in a local repository. When you install an application, Flatpak fetches only the changed objects from the remote, similar to how Git fetches commits. This makes updates efficient even for large applications.
26+
27+
Applications either bundle their own libraries directly or declare runtime dependencies, such as `org.freedesktop.Platform` or `org.gnome.Platform`. The runtime provides a consistent base set of libraries, such as libc and GTK, that multiple applications can share on disk, reducing total storage. The application and its runtime are kept separate from the host system libraries, which means you don't need to resolve conflicts.
28+
29+
For Arm developers, the key advantage is that Flatpak applications can publish separate builds for `x86_64` and `aarch64` under the same application ID. Flatpak selects the correct architecture automatically at install time.
30+
31+
## How does Flatpak compare to Linux package managers?
32+
33+
Linux package managers like `apt`, `dnf`, and `pacman` are tightly coupled to the distribution release cycle. An application packaged for Ubuntu 24.04 may lag the upstream version, and some applications aren't packaged for every Linux distribution. Flatpak addresses this by letting upstream developers publish and maintain their own builds directly on Flathub. This allows you to get the current release of an application on any supported Linux distribution.
34+
35+
Because a Flatpak application bundles its own libraries or pins a specific runtime version, installing or updating it can't conflict with host system libraries or break other packages. A distro upgrade won't silently change the libraries an application links against. This also means you can run two different applications that require incompatible versions of the same library side by side without issues.
36+
37+
The instructions below cover installing Flatpak on Arm Linux (aarch64), adding the Flathub remote, and verifying the installation by installing VSCodium.
38+
39+
## Before you begin
40+
41+
Confirm your system is running a 64-bit Arm Linux distribution:
42+
43+
```bash
44+
uname -m
45+
```
46+
47+
The output should be:
48+
49+
```output
50+
aarch64
51+
```
52+
53+
## How do I install Flatpak?
54+
55+
### Ubuntu or Debian
56+
57+
Update your package lists and install Flatpak:
58+
59+
```bash
60+
sudo apt update
61+
sudo apt install -y flatpak
62+
```
63+
64+
### Fedora
65+
66+
Install Flatpak using DNF:
67+
68+
```bash
69+
sudo dnf install -y flatpak
70+
```
71+
72+
### Arch or Manjaro
73+
74+
Sync the package database and install Flatpak:
75+
76+
```bash
77+
sudo pacman -S --noconfirm flatpak
78+
```
79+
80+
### openSUSE
81+
82+
Refresh the repository metadata and install Flatpak:
83+
84+
```bash
85+
sudo zypper refresh
86+
sudo zypper install -y flatpak
87+
```
88+
89+
After installing, log out and back in to ensure desktop integration works correctly.
90+
91+
## Verify Flatpak is installed
92+
93+
Confirm Flatpak is available and check the version:
94+
95+
```bash
96+
flatpak --version
97+
```
98+
99+
The output will look similar to:
100+
101+
```output
102+
Flatpak 1.16.1
103+
```
104+
105+
## How do I add the Flathub remote?
106+
107+
Add the Flathub repository as a remote source:
108+
109+
```bash
110+
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
111+
```
112+
113+
Confirm the remote was added:
114+
115+
```bash
116+
flatpak remotes
117+
```
118+
119+
The output should include a line for `flathub`:
120+
121+
```output
122+
Name Options
123+
flathub system
124+
```
125+
126+
## How do I install the VSCodium Flatpak?
127+
128+
[VSCodium](https://vscodium.com/) is the telemetry-free build of VS Code, available on Flathub with a native Arm build, making it a useful application to test.
129+
130+
Install it with the `--assumeyes` flag, which automatically answers yes to any prompts during installation:
131+
132+
```bash
133+
flatpak install --assumeyes flathub com.vscodium.codium
134+
```
135+
136+
Confirm the installation and check the architecture:
137+
138+
```bash
139+
flatpak info com.vscodium.codium
140+
```
141+
142+
The output includes the runtime architecture:
143+
144+
```output
145+
VSCodium - Telemetry-less code editing
146+
147+
ID: com.vscodium.codium
148+
Ref: app/com.vscodium.codium/aarch64/stable
149+
Arch: aarch64
150+
Branch: stable
151+
Version: 1.112.01907
152+
License: MIT
153+
Origin: flathub
154+
Collection: org.flathub.Stable
155+
Installation: system
156+
Installed: 500.4 MB
157+
Runtime: org.freedesktop.Sdk/aarch64/25.08
158+
Sdk: org.freedesktop.Sdk/aarch64/25.08
159+
160+
Commit: 941b853cf7e254f628e79549ff39b2940faeb11a0c022485507ee83af7d1ffb9
161+
Parent: 8bf491c5bb50857418982dea2cf3a78ca127e888f8055332cf11650ab7472b99
162+
Subject: fix: :fire: Remove urls to fix all the appstream validationwarnings (92763b676197)
163+
Date: 2026-03-30 05:03:53 +0000
164+
```
165+
166+
The `Arch: aarch64` line confirms a native Arm build is installed.
167+
168+
To start VSCodium on the project in your current directory, run:
169+
170+
```bash
171+
flatpak run com.vscodium.codium . &
172+
```
173+
174+
You can also create an alias to make it easier:
175+
176+
```bash
177+
alias codium='flatpak run com.vscodium.codium'
178+
```
179+
180+
Now, run using the alias:
181+
182+
```bash
183+
codium . &
184+
```
185+
186+
## What are some other useful Flatpak commands?
187+
188+
If an installation becomes corrupted or incomplete, run `flatpak repair` to check your local Flatpak installation and fix any inconsistencies:
189+
190+
```bash
191+
flatpak repair
192+
```
193+
194+
To update all installed Flatpak applications and runtimes to their latest versions, run:
195+
196+
```bash
197+
flatpak update
198+
```
199+
200+
To inspect the sandbox permissions granted to an application, run:
201+
202+
```bash
203+
flatpak info --show-permissions com.vscodium.codium
204+
```
205+
206+
To open an interactive shell inside an application's sandbox, which is useful for debugging permission or runtime issues, run:
207+
208+
```bash
209+
flatpak run --command=bash com.vscodium.codium
210+
```
211+
212+
Note that not all applications include `bash` in their sandbox, so this command may not work for every Flatpak. Your shell prompt may not look any different, but you are in the sandbox. To confirm run:
213+
214+
```bash
215+
ls /app
216+
cat /etc/os-release
217+
```
218+
219+
The output is similar to:
220+
221+
```output
222+
bin lib manifest-base-1.json manifest.json share tools
223+
NAME="Freedesktop SDK"
224+
VERSION="25.08 (Flatpak runtime)"
225+
VERSION_ID=25.08
226+
ID=org.freedesktop.platform
227+
PRETTY_NAME="Freedesktop SDK 25.08 (Flatpak runtime)"
228+
BUG_REPORT_URL=https://gitlab.com/freedesktop-sdk/freedesktop-sdk/issues
229+
```
230+
231+
The `/app` directory contains the application runtime files, and the `os-release` file shows the Flatpak runtime rather than the host OS.
232+
233+
## How can I find Arm-native applications on Flathub?
234+
235+
Flatpak makes it straightforward to discover which applications support aarch64. Visit the [Flathub app browser](https://flathub.org/apps) and filter by architecture to find applications with native Arm builds. You can also search from the command line after adding the Flathub remote:
236+
237+
```bash
238+
flatpak remote-ls --app --arch=aarch64 flathub
239+
```
240+
241+
This lists every application on Flathub that publishes a native aarch64 build. Use `grep` to narrow results by name or category.
242+
243+
## Uninstall
244+
245+
To remove VSCodium, run:
246+
247+
```bash
248+
flatpak uninstall --assumeyes com.vscodium.codium
249+
```
250+
251+
To remove the Flathub remote, run:
252+
253+
```bash
254+
sudo flatpak remote-delete flathub
255+
```

0 commit comments

Comments
 (0)