Flatpak

Motrix’s official Flatpak uses the application ID app.motrix.native. This guide covers the .flatpak bundles distributed through GitHub Releases, plus the optional Native Messaging host for browser integration.

Choose the files#

Open a Motrix 2 release and check its Assets list. The application and the browser companion are separate downloads:

uname -m	Application bundle	Native Host companion
x86_64	Motrix-VERSION-x86_64.flatpak	Motrix-Native-Host-VERSION-linux-x64.tar.gz
aarch64	Motrix-VERSION-aarch64.flatpak	Motrix-Native-Host-VERSION-linux-arm64.tar.gz

Choose both files from the same release if you plan to use the browser extension. The companion is optional for downloads entered directly in Motrix. VERSION is a placeholder for the release version without the leading v; replace it with the value in the downloaded filename.

The commands below use x86_64/x64 filenames. On ARM64, use aarch64/arm64 respectively.

Install the application#

Install Flatpak through your distribution’s package manager if needed; see Flatpak setup for your distribution. This guide uses a per-user installation (--user). Run the following commands as your regular desktop user, without sudo.

Add Flathub as a remote for the shared runtimes, then install the downloaded bundle:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user --or-update ./Motrix-VERSION-x86_64.flatpak
flatpak info --user app.motrix.native
flatpak run app.motrix.native

Flatpak resolves the required runtime during installation. Adding this remote supplies dependencies; the Motrix application in this guide comes from the local bundle. It does not subscribe the application to a Motrix update repository.

Beta releases use the beta branch; stable releases use stable. You can check the installed branch with flatpak info. When using the browser companion, keep only one Motrix branch installed and avoid installing the same application in both the user and system installations, so the browser launches the intended copy.

On first launch, complete Motrix’s language and usage-notice setup before pairing the browser extension.

Files and permissions#

The default sandbox permissions include the XDG download directory. Use Motrix’s directory chooser to grant access to another location through the desktop portal. If the chooser does not work, check that your distribution has xdg-desktop-portal and a portal backend suitable for your desktop environment.

Motrix’s Flatpak configuration and application data live under ~/.var/app/app.motrix.native/. Existing settings and tasks from DEB, RPM, AppImage, or the legacy Flatpak are not migrated automatically. Files downloaded outside that directory remain in the destination you selected.

Browser integration#

The browser starts a Native Messaging host on the host system, while Motrix runs inside the Flatpak sandbox. The companion, motrix-flatpak-native-host, connects these two environments. The application includes the sandbox-side broker; you install the companion separately and register it for your user account.

Supported browsers#

The installer writes Native Messaging manifests for Chrome, Chromium, Microsoft Edge, and Firefox installed on the host system. Use the official Motrix Extension.

A browser installed as a Flatpak or Snap has its own sandbox. Its packaging may require a separately supported Native Messaging proxy; installing the Motrix companion alone does not establish compatibility. If the extension cannot find the host, check the browser package’s documentation.

Install the Native Messaging host#

After installing Motrix, extract the matching companion archive in a directory owned by your user, then run the installer without sudo:

tar -xzf Motrix-Native-Host-VERSION-linux-x64.tar.gz
cd Motrix-Native-Host-VERSION-linux-x64
./motrix-flatpak-native-host install
./motrix-flatpak-native-host status

The installer copies the executable and writes the browser manifests to user-level locations. With the default XDG paths, the executable is installed at ~/.local/share/motrix/native-messaging/motrix-flatpak-native-host and its configuration at ~/.config/motrix/native-messaging/flatpak-companion.json. If you set XDG_DATA_HOME or XDG_CONFIG_HOME, those locations are used instead. You can remove the extracted archive directory after a successful installation.

The installer expects Flatpak at /usr/bin/flatpak. If your distribution uses another location, pass its absolute path:

./motrix-flatpak-native-host install --flatpak-bin /absolute/path/to/flatpak

Open Motrix, enable Settings → Integration → Browser extensions → Send downloads from browser extensions, then follow the pairing instructions. When updating an existing installation, use the upgrade commands below.

Pairing details#

The companion currently registers only Motrix’s built-in official extension IDs. Adding a custom or unpacked extension ID in Motrix does not add it to the companion’s browser manifests.

With Firefox, the first pairing may show the extension identity as unverified. The Flatpak companion does not currently provide a Native Messaging identity ticket (nmTicket). Confirm that you initiated the request, then enter the pairing code shown by Motrix. The identity label alone does not mean that the connection failed.

If the extension cannot connect#

1. Check flatpak info --user app.motrix.native, then start Motrix manually with flatpak run app.motrix.native. Complete the first-launch setup and confirm that browser integration is enabled.

2. Check the installed companion:

   "${XDG_DATA_HOME:-$HOME/.local/share}/motrix/native-messaging/motrix-flatpak-native-host" status

   installed confirms the companion configuration and manifests, not a completed browser connection. If the command is missing, install the companion first. If it reports an error, use that error to check the installation paths or configuration.

3. Confirm that the browser is installed on the host, or that its sandboxed package supports an appropriate Native Messaging proxy. Retry pairing after restarting the browser.

4. If pairing still fails, use Diagnose in the extension’s connection error panel. Include the report, your distribution, browser installation source, Motrix version, and companion status output when reporting the issue.

The installer rejects symlinks, unexpected ownership, and group- or world-writable directories in its installation paths. Run it under the same account as your browser and inspect the reported path rather than granting broader write permissions.

Update#

Quit Motrix, download the new .flatpak for the same architecture and branch, and install it over the existing application:

flatpak install --user --or-update ./Motrix-VERSION-x86_64.flatpak

These single-file bundles have no Motrix update remote configured. flatpak update --user can update runtimes from Flathub, but it does not discover new Motrix bundles on GitHub. Download and install each new application bundle yourself; do not rely on Motrix’s in-app updater for this installation.

If you use browser integration, download and extract the companion from the same new release. From the newly extracted directory, run:

./motrix-flatpak-native-host install --force
./motrix-flatpak-native-host status

--force replaces the existing companion installation/configuration. If you use a nonstandard Flatpak executable, include --flatpak-bin /absolute/path/to/flatpak again. Updating the .flatpak does not update the host-side companion.

Uninstall or switch package formats#

If you installed the companion, remove its registration before uninstalling the application:

"${XDG_DATA_HOME:-$HOME/.local/share}/motrix/native-messaging/motrix-flatpak-native-host" uninstall
flatpak uninstall --user app.motrix.native

The companion command removes its executable, configuration, and managed browser manifests. Flatpak normally retains application data. Add --delete-data to the Flatpak uninstall command only if you also want to remove the application’s saved data.

Before switching browser integration to a DEB, RPM, or Snap installation, uninstall the Flatpak companion. It owns Motrix’s shared browser manifests while installed; other Motrix package formats will not overwrite them.