Skip to content

Commit 9e6280b

Browse files
jasonrandrewsjasonrandrews
committed
Flatpak install guide
1 parent 86b7b81 commit 9e6280b

1 file changed

Lines changed: 254 additions & 0 deletions

File tree

‎content/install-guides/flatpak.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
---
2+
title: "Flatpak"
3+
minutes_to_complete: 10
4+
official_docs: "https://flatpak.org"
5+
author: "Jason Andrews"
6+
weight: 1
7+
draft: true
8+
tool_install: true
9+
layout: installtoolsall
10+
multi_install: false
11+
multitool_install_part: false
12+
---
13+
14+
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.
15+
16+
## How does Flatpak sandboxing work?
17+
18+
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.
19+
20+
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`.
21+
22+
## How are Flatpak applications packaged?
23+
24+
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.
25+
26+
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.
27+
28+
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.
29+
30+
## How does Flatpak compare to Linux package managers?
31+
32+
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.
33+
34+
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.
35+
36+
The instructions below cover installing Flatpak on Arm Linux (aarch64), adding the Flathub remote, and verifying the installation by installing VSCodium.
37+
38+
## Before you begin
39+
40+
Confirm your system is running a 64-bit Arm Linux distribution:
41+
42+
```bash
43+
uname -m
44+
```
45+
46+
The output should be:
47+
48+
```output
49+
aarch64
50+
```
51+
52+
## How do I install Flatpak?
53+
54+
### Ubuntu or Debian
55+
56+
Update your package lists and install Flatpak:
57+
58+
```bash
59+
sudo apt update
60+
sudo apt install -y flatpak
61+
```
62+
63+
### Fedora
64+
65+
Install Flatpak using DNF:
66+
67+
```bash
68+
sudo dnf install -y flatpak
69+
```
70+
71+
### Arch or Manjaro
72+
73+
Sync the package database and install Flatpak:
74+
75+
```bash
76+
sudo pacman -S --noconfirm flatpak
77+
```
78+
79+
### openSUSE
80+
81+
Refresh the repository metadata and install Flatpak:
82+
83+
```bash
84+
sudo zypper refresh
85+
sudo zypper install -y flatpak
86+
```
87+
88+
After installing, log out and back in to ensure desktop integration works correctly.
89+
90+
## Verify Flatpak is installed
91+
92+
Confirm Flatpak is available and check the version:
93+
94+
```bash
95+
flatpak --version
96+
```
97+
98+
The output will look similar to:
99+
100+
```output
101+
Flatpak 1.16.1
102+
```
103+
104+
## How do I add the Flathub remote?
105+
106+
Add the Flathub repository as a remote source:
107+
108+
```bash
109+
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
110+
```
111+
112+
Confirm the remote was added:
113+
114+
```bash
115+
flatpak remotes
116+
```
117+
118+
The output should include a line for `flathub`:
119+
120+
```output
121+
Name Options
122+
flathub system
123+
```
124+
125+
## How do I install the VSCodium Flatpak?
126+
127+
[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.
128+
129+
Install it with the `--assumeyes` flag, which automatically answers yes to any prompts during installation:
130+
131+
```bash
132+
flatpak install --assumeyes flathub com.vscodium.codium
133+
```
134+
135+
Confirm the installation and check the architecture:
136+
137+
```bash
138+
flatpak info com.vscodium.codium
139+
```
140+
141+
The output includes the runtime architecture:
142+
143+
```output
144+
VSCodium - Telemetry-less code editing
145+
146+
ID: com.vscodium.codium
147+
Ref: app/com.vscodium.codium/aarch64/stable
148+
Arch: aarch64
149+
Branch: stable
150+
Version: 1.112.01907
151+
License: MIT
152+
Origin: flathub
153+
Collection: org.flathub.Stable
154+
Installation: system
155+
Installed: 500.4 MB
156+
Runtime: org.freedesktop.Sdk/aarch64/25.08
157+
Sdk: org.freedesktop.Sdk/aarch64/25.08
158+
159+
Commit: 941b853cf7e254f628e79549ff39b2940faeb11a0c022485507ee83af7d1ffb9
160+
Parent: 8bf491c5bb50857418982dea2cf3a78ca127e888f8055332cf11650ab7472b99
161+
Subject: fix: :fire: Remove urls to fix all the appstream validationwarnings (92763b676197)
162+
Date: 2026-03-30 05:03:53 +0000
163+
```
164+
165+
The `Arch: aarch64` line confirms a native Arm build is installed.
166+
167+
To start VSCodium on the project in your current directory, run:
168+
169+
```bash
170+
flatpak run com.vscodium.codium . &
171+
```
172+
173+
You can also create an alias to make it easier:
174+
175+
```bash
176+
alias codium='flatpak run com.vscodium.codium'
177+
```
178+
179+
Now, run using the alias:
180+
181+
```bash
182+
codium . &
183+
```
184+
185+
## What are some other useful Flatpak commands?
186+
187+
If an installation becomes corrupted or incomplete, run `flatpak repair` to check your local Flatpak installation and fix any inconsistencies:
188+
189+
```bash
190+
flatpak repair
191+
```
192+
193+
To update all installed Flatpak applications and runtimes to their latest versions, run:
194+
195+
```bash
196+
flatpak update
197+
```
198+
199+
To inspect the sandbox permissions granted to an application, run:
200+
201+
```bash
202+
flatpak info --show-permissions com.vscodium.codium
203+
```
204+
205+
To open an interactive shell inside an application's sandbox, which is useful for debugging permission or runtime issues, run:
206+
207+
```bash
208+
flatpak run --command=bash com.vscodium.codium
209+
```
210+
211+
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:
212+
213+
```bash
214+
ls /app
215+
cat /etc/os-release
216+
```
217+
218+
The output is similar to:
219+
220+
```output
221+
bin lib manifest-base-1.json manifest.json share tools
222+
NAME="Freedesktop SDK"
223+
VERSION="25.08 (Flatpak runtime)"
224+
VERSION_ID=25.08
225+
ID=org.freedesktop.platform
226+
PRETTY_NAME="Freedesktop SDK 25.08 (Flatpak runtime)"
227+
BUG_REPORT_URL=https://gitlab.com/freedesktop-sdk/freedesktop-sdk/issues
228+
```
229+
230+
The `/app` directory contains the application runtime files, and the `os-release` file shows the Flatpak runtime rather than the host OS.
231+
232+
## How can I find Arm-native applications on Flathub?
233+
234+
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:
235+
236+
```bash
237+
flatpak remote-ls --app --arch=aarch64 flathub
238+
```
239+
240+
This lists every application on Flathub that publishes a native aarch64 build. Use `grep` to narrow results by name or category.
241+
242+
## Uninstall
243+
244+
To remove VSCodium, run:
245+
246+
```bash
247+
flatpak uninstall --assumeyes com.vscodium.codium
248+
```
249+
250+
To remove the Flathub remote, run:
251+
252+
```bash
253+
sudo flatpak remote-delete flathub
254+
```

0 commit comments

Comments
 (0)