Flatpak is a portable software packager for native Linux software deployment. It has been designed to offer a sandbox environment in which users can run applications in isolation from the rest of the system. This means that Flatpak software can run on virtually any Linux distribution… including Batocera.

This is currently supported only for x86_64, as most Flatpak packages are only provided for Linux on the x86/x86_64 platform.

Although we aim to have all Flatpaks functioning, we can't guarantee 100% compatibility; audio tends to be a common issue. Report any issues you find to our Github/Discord server (check for duplicates first).

Common issues: no PS4 controller support, cannot install Flatpaks if using a NAS for your SAVES directory, audio is absent on some configurations, some games think the D-pad is eternally being pressed down on certain controllers, apps that depend on opening the file browser crash upon doing so, etc.

If you still want to use a NAS for the rest of your systems' saves, Flatpaks can still be installed to internal storage as a workaround.

Steam, Heroic, GeForce NOW and Bottles have their own pages.

This system scrapes metadata for the “flatpak” group and loads the flatpak set from the currently selected theme, if available.

Grouped with the “ports” group of systems.

The default Flatpak repository: Flathub.

  • Emulator: Flatpak
  • Folder: /userdata/roms/flatpak
  • Accepted ROM formats: .flatpak

Unlike with most systems, Flatpaks aren't actually installed to its ROM folder at /userdata/roms/flatpak. No no, here only the shortcuts to them are stored. The actual Flatpaks themselves are installed to the SAVEs folder at /userdata/saves/flatpak.

On Batocera v31, if this is your first time using Flatpak on the system, you'll have to add the repository first. One of the most popular is the Flathub repo. To do that, first connect to your Batocera via SSH or use xterm ([F1] on system list → Applications) and run the following command (while connected to the internet):

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

Batocera v32 and higher already have this set as the default repository.

In Batocera v32 and higher, you can then launch flatpak-config from the file manager ([F1] → Applications) to search for and install Flatpaks.

F1 -> Applications

The flatpak-config menu. Pretty basic but it works.

Two cursors on-screen?

There's a bug affecting v32 where two cursors are displayed. The one you're controlling is the white one. This has since been fixed.

Screenshot showing both the white and black cursors. It's like that one gif of Spiderman pointing at himself.

This is also where you would upgrade your packages in the future.

First of all, you need to connect to Batocera through SSH.

Then, you need to add your Flatpak remote repo to the system. One of the most popular is the Flathub repo.

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

Once your repo is added, you can search for the software you want to install. In our example here, we are going to install Steam. So, let's search for it:

 flatpak search Steam
 Name               Description                               Application ID                   Version       Branch Remotes
 Steam              Manage and play games distributed by Ste? com.valvesoftware.Steam      stable flathub
 Boxtron            Compatibility tool to run DOS games on S? ?Steam.CompatibilityTool.Boxtron               stable flathub
 vkBasalt           A Vulkan post processing layer for Linux  ?software.Steam.Utility.vkBasalt       stable flathub
 protontricks       A simple wrapper that does winetricks th? ?ware.Steam.Utility.protontricks 1.5.2         stable flathu

The piece of software we want to install, Valve's Steam client, is the first one. It can be installed with:

 flatpak install com.valvesoftware.Steam
 Looking for matches?
 Found similar ref(s) for ?com.valvesoftware.Steam? in remote ?flathub? (system).
 Use this remote? [Y/n]: Y
 Required runtime for com.valvesoftware.Steam/x86_64/stable (runtime/org.freedesktop.Platform/x86_64/20.08) found in remote flathub
 Do you want to install it? [Y/n]: Y
 com.valvesoftware.Steam permissions:
   ipc                              network                  pulseaudio               wayland
   x11                              devices                  bluetooth                devel
   multiarch                        per-app-dev-shm          file access [1]          dbus access [2]
   system dbus access [3]           tags [4]
  [1] xdg-music:ro, xdg-pictures:ro, xdg-run/app/com.discordapp.Discord:create
  [2] org.freedesktop.Notifications, org.freedesktop.PowerManagement, org.freedesktop.ScreenSaver,
      org.gnome.SettingsDaemon.MediaKeys, org.kde.StatusNotifierWatcher
  [3] org.freedesktop.UDisks2, org.freedesktop.UPower
  [4] proprietary
        ID                                             Branch          Op          Remote           Download
 1.     org.freedesktop.Platform.Compat.i386           20.08           i           flathub          < 152.6?MB
 2.     org.freedesktop.Platform.GL.default            20.08           i           flathub          < 106.4?MB
 3.     org.freedesktop.Platform.GL32.default          20.08           i           flathub          < 114.1?MB
 4.     org.freedesktop.Platform.Locale                20.08           i           flathub          < 322.2?MB
 5.     org.freedesktop.Platform.VAAPI.Intel           20.08           i           flathub           < 11.6?MB
 6.     org.freedesktop.Platform.openh264              2.0             i           flathub            < 1.5?MB
 7.     org.freedesktop.Platform                       20.08           i           flathub          < 268.1?MB
 8.     com.valvesoftware.Steam                        stable          i           flathub           < 13.5?MB
 Proceed with these changes to the system installation? [Y/n]
        ID                                             Branch          Op          Remote           Download
 1. [?] org.freedesktop.Platform.Compat.i386           20.08           i           flathub          140.4?MB / 152.6?MB
 2. [?] org.freedesktop.Platform.GL.default            20.08           i           flathub          105.8?MB / 106.4?MB
 3. [?] org.freedesktop.Platform.GL32.default          20.08           i           flathub          113.8?MB / 114.1?MB
 4. [?] org.freedesktop.Platform.Locale                20.08           i           flathub          140.6?MB / 322.2?MB
 5. [?] org.freedesktop.Platform.VAAPI.Intel           20.08           i           flathub           11.5?MB / 11.6?MB
 6. [?] org.freedesktop.Platform.openh264              2.0             i           flathub            1.5?MB / 1.5?MB
 7. [?] org.freedesktop.Platform                       20.08           i           flathub          222.5?MB / 268.1?MB
 8. [?] com.valvesoftware.Steam                        stable          i           flathub           12.3?MB / 13.5?MB
 Installation complete.

Now, the Flatpak package is installed, but you need to tell Batocera to show it up in the EmulationStation menu (under Ports):

 adding Steam
 updating permissions on files.

Let's say you've got yourself a fine and dandy Flatpak package in its physical folder form and you want to tell Batocera to just use that instead of searching for it in a repository. This is simple:

  1. Move the folder containing your Flatpak package to roms/flatpak/
  2. Then just run flatpak install <name of package>

So for example if I had emby-theater-snap_3.0.15_amd64, I would move it to roms/flatpak/emby-theater-snap_3.0.15_amd64 and then run:

flatpak install emby-theater-snap_3.0.15_amd64.snap

Note: Flatpak is an isolated environment by default unless you are configuring it otherwise manually. Therefore you can always safely update any flatpak packages without having to worry your Batocera system will be affected in any way other than flatpak package installations. All packages appearing in the flatpak-config update list are only part of existing flatpak package installations on your system and will only affect those. However, keep in mind, that updating those packages could affect an existing flatpak package installation in a negative way but this is very unlikely. Generally said, it is safe for existing flatpak package installations to install any of those updates.

Updating Flatpak packages is simple: open flatpak-config and click Upgrade. All applicable packages will be updated to their latest version. You may be asked to reboot.

Alternatively, this can be done by running the following command via SSH:

flatpak update

Type in Y and hit [Enter].

:-( A sometimes necessary evil.

You can use the same flatpak-config tool to remove them or run the command:

flatpak uninstall <name-of-package-here>

Don't worry about spelling the package's name precisely, Flatpak will search your system for matching results and ask you if it's the correct one to uninstall first.

Unfortunately, for now at least, the .flatpak file from the /userdata/roms/ directory must be removed manually in order to remove the entry from your game list too.

This command used to be buggy on v32 and below, it is not advised to use it on older Batocera versions. Link to the related issue report.

So you've been using Flatpak packages for a while now, you may have noticed that some applications need to install “runtimes” and other libraries to function. It's safe to leave these packages, and even multiple versions of the same package even, on a system after you no longer need the package that initially installed it. However over time they can take up quite some space, especially if you've been installing and uninstalling games as you play through them.

So you could uninstall these packages one by one, but that would take an inordinate amount of time especially if you have to shift through which packages are really no longer required and which ones are. There's a simple command you can run instead to do all that for you:

flatpak uninstall --unused

Here are some lists of freely distributed Linux games!

Here are the default controls used in Flatpak games shown on a Batocera Retropad:

Obviously, applications designed for a mouse and keyboard interface will probably only work when those are connected.

Try one of the following:

  • Update your game list: Main MenuGame SettingsUpdate Gamelists.
  • Flatpaks currently do not work on a NAS, if you are using a NAS try switching to internal storage.
  • The application may need to not be run in the sandbox. From SSH, run flatpak run <name-of-package> --no-sandbox to test for this.

    This can be launched directly from ES by using an SH script in the ports system.

    For example, to launch the Heroic Games launcher without sandbox, save the following file to roms/ports and then update the gamelist:

    flatpak run com.heroicgameslauncher.hgl --no-sandbox
  • SSH into Batocera and run the following: batocera-flatpak-update
  • If you are on an older Batocera version (like v31 or lower) it might be a permissions issue.
    1. Press [F1] on your keyboard to enter into File Manager
    2. Ensure you are in the Share folder (left in the sidebar)
    3. Navigate to the saves folder
    4. Select everything by pressing [Ctrl] + [A]
    5. Right-click and go to Properties
    6. Click on the “Permissions” tab
    7. Click on “View Content:” and choose “Anyone”
    8. Click on “Change Content:” and choose “Anyone”
    9. Click on “Access content:” and choose “Anyone”
    10. Click on “OK”
    11. Reboot and try it
  • If trying to run a Flatpak of a Windows game via a Flatpak of Wine (yes, it is complicated and there are many things that can go wrong), search the game on the ProtonDB and see what other users have said they've had to do to make it work. You may need to utilize custom launch commands to get a game working.
  • Flatpak can be effectively reset to its default state by deleting the /userdata/saves/flatpak/ and /userdata/roms/flatpak/ folders.
    • Sometimes, Flatpak will “forget” that you have drivers and will need to “redownload” them (you'll find Steam is suddenly lagging in its menus). Run flatpak update in the SSH and if it starts downloading org.freedesktop.Platform.GL.nvidia-###-##-## then that is what happened.
  • Try reinstalling the game and ensure all of its dependencies are sorted out, with no errors.
  • PC games in general (especially ones that were ported from home consoles to PC) can be buggy. Check out the PCGamingWiki for general tips, settings configurations, launch commands and patches you can apply to fix the game (just keep in mind it's focused on Windows, not Linux (and thus, not Batocera) so a lot of external programs/patches won't be compatible).

Unfortunately some games are just garbage at supporting certain controllers. Refer to the PCGamingWiki for general tips, but if you're still struggling to get your controller recognized by the game, see if it would be possible to get the game running from Steam. Once that's done, it should be possible to use Steam to configure the controls, allowing you to use any controller that would be compatible with Steam instead.

For further troubleshooting, refer to the generic support pages.

  • systems/flatpak.txt
  • Last modified: 4 months ago
  • by maximumentropy