If the BitBoxApp fails to install or does not start correctly on Linux, the issue is usually caused by an unsupported Linux distribution, an incomplete download, missing execution permissions, package manager restrictions, insufficient administrator permissions, or security software blocking the app.

Complete the basic checks below, then use the troubleshooting section that matches your Linux installation method or the behavior you see.

Before you begin

1. Check whether your Linux distribution is supported. Unsupported distributions or operating system versions can prevent the BitBoxApp from installing or opening correctly. Check the supported operating systems for the BitBoxApp to confirm that your Linux distribution is supported.
2. Update Linux. Install the latest operating system updates available for your distribution. This helps ensure compatibility with the latest BitBoxApp version and allows system security features and package managers to work as expected.
3. Restart your computer. Restarting Linux can resolve temporary startup issues, release files or package-manager locks, and complete pending update processes.

Troubleshooting

Download a fresh BitBoxApp file

An incomplete or damaged download can prevent the BitBoxApp package or AppImage from opening correctly.

1. Delete the downloaded BitBoxApp package or AppImage from your Downloads folder. Do not install or run it if it came from an unofficial source.
2. Open the official BitBox download page.
3. Download the latest BitBoxApp file for your Linux installation method.
   1. Use the .deb package for Debian-based distributions.
   2. Use the .rpm package for RPM-based distributions.
   3. Use the AppImage if you prefer a portable app file or if your distribution does not use DEB or RPM packages.

If you want to verify the new download, you can verify the BitBoxApp checksum. Advanced users can also verify the BitBoxApp signature on Linux.

The downloaded file should now open normally with the installation method that matches your distribution.

Check your Linux distribution and package type

The BitBoxApp Linux package must match your Linux distribution.

1. Use the .deb package on Debian-based distributions such as Debian, Ubuntu, Linux Mint, Pop!_OS, and Zorin OS.
2. Use the .rpm package on RPM-based distributions such as Fedora, openSUSE, and Red Hat Enterprise Linux compatible distributions.
3. Use the AppImage if your Linux distribution does not support the official DEB or RPM package format.
4. If you downloaded the wrong package type, delete it and download the correct file from the official BitBox download page.
5. If your distribution is not supported, use a supported distribution or try the AppImage when appropriate.

The selected BitBoxApp file should now match your Linux distribution and installation method.

If a DEB or RPM package fails

Package installation can fail if your Linux package manager blocks the installation, administrator permissions are missing, the wrong package type was downloaded, or your operating system is unsupported or outdated.

1. Confirm that you downloaded the correct .deb or .rpm package for your distribution.
2. Open the package with your system package manager.
3. Approve the installation if your Linux system asks for confirmation.
4. Enter your administrator password if your Linux system asks for it.
5. Wait until the package manager reports that the installation is complete.
6. Open the BitBoxApp from your applications menu.

If the package manager continues to report an error, install available operating system updates, download a fresh BitBoxApp package, and repeat the installation. The package manager should then complete the installation and the BitBoxApp should open normally.

If the AppImage does not start

Linux usually disables execution permissions for downloaded files. If the BitBoxApp AppImage does not start, make the AppImage executable first.

1. Open your file manager.
2. Go to the folder that contains the downloaded BitBoxApp AppImage.
3. Right-click the AppImage file.
4. Select Properties.
5. Open the Permissions or Access Rights tab.
6. Enable Allow executing file as program, if your desktop environment shows this option.
7. Close the properties window.
8. Double-click the AppImage again.

If your desktop environment does not show an executable permission option, follow the steps to run the BitBoxApp AppImage on Linux from the terminal.

The BitBoxApp AppImage should now start.

Check security software or managed device policies

Antivirus software, endpoint protection tools, browser security settings, corporate device policies, or restricted user permissions can block the BitBoxApp download, installation, or startup.

1. Check whether your browser blocked the downloaded BitBoxApp file.
2. Check whether security software quarantined or blocked the downloaded package or AppImage.
3. If you use a managed work, school, or company computer, ask your device administrator whether software installation or AppImage execution is restricted.
4. Download the latest BitBoxApp file again after the block is resolved.
5. Install the package again or start the AppImage again.

The BitBoxApp should now be allowed to install or start.

If the BitBoxApp does not open after installation

If the BitBoxApp closes immediately, no window appears, or nothing happens after installation, the installation may be incomplete or your Linux environment may still be blocking the app.

1. Close the BitBoxApp if any BitBoxApp window is open.
2. Restart your computer.
3. Open the BitBoxApp again from your applications menu or start the AppImage again.
4. If the BitBoxApp still does not open, remove the installed BitBoxApp package or delete the AppImage file.
5. Download the latest BitBoxApp file again from the official BitBox download page.
6. Install the package again or make the AppImage executable again.
7. Open the BitBoxApp.

The BitBoxApp should now open normally.

If the BitBoxApp still shows an old version

Installing the latest Linux package normally updates the existing BitBoxApp installation. The AppImage does not update automatically and must be replaced manually.

1. Open the BitBoxApp.
2. Open Settings → About.
3. Compare the displayed BitBoxApp version with the latest stable BitBoxApp release in the official GitHub repository.
4. Only if the versions do not match, close the BitBoxApp completely.
5. Remove the installed BitBoxApp package or delete the old AppImage file.
6. Download the latest Linux package or AppImage from the official BitBox download page.
7. Install the new package or start the new AppImage.
8. Open Settings → About and compare the displayed version again.

The version shown in Settings → About should match the latest stable BitBoxApp release published in the official BitBoxApp GitHub releases repository. If it does, you are running the latest installed or downloaded version.

If your BitBox is not detected after installation

If the BitBoxApp opens but does not detect your BitBox, the installation itself is normally complete. Follow the steps to troubleshoot BitBox detection on Linux.

Frequently asked questions

Why does the AppImage not start when I double-click it?

Linux usually disables execution permissions for downloaded files. Make the BitBoxApp AppImage executable first, then start it again. To use either the file manager method or the terminal method, follow the steps to run the BitBoxApp AppImage on Linux.

Should I use the DEB, RPM, or AppImage?

Use the .deb package for Debian-based distributions and the .rpm package for RPM-based distributions. Use the AppImage if you prefer a portable app file or if your distribution does not use DEB or RPM packages. To choose the right method, follow the steps to install the BitBoxApp on Linux or run the BitBoxApp AppImage on Linux.

Do I need administrator permissions to install the BitBoxApp on Linux?

Usually, yes. Installing a DEB or RPM package often requires administrator permissions. The AppImage does not require package manager installation, but your system may still require permission to run downloaded executable files.

Can security software prevent the BitBoxApp from installing on Linux?

Yes. Antivirus software, endpoint protection, browser security settings, corporate device policies, or restricted user permissions can prevent the BitBoxApp from downloading, installing, or starting.

Does the BitBoxApp support every Linux distribution?

No. The BitBoxApp supports selected Linux distributions and operating system versions. Check the supported operating systems for the BitBoxApp before troubleshooting installation issues.

Will reinstalling the BitBoxApp remove my funds?

No. Reinstalling the BitBoxApp does not remove your funds. Your cryptocurrencies remain on their respective blockchain, while access to them is secured by your BitBox02 and your wallet backup.

Why does the BitBoxApp open but not detect my BitBox?

If the BitBoxApp opens but does not detect your BitBox, the installation itself is usually complete. Follow the steps to troubleshoot BitBox detection on Linux, including USB detection, udev rules, and permissions.

When should I contact BitBox support?

Contact BitBox Support through the official Support contact form if the package still does not install, the AppImage does not start after you made it executable, the BitBoxApp still does not open after reinstalling, or Linux continues to block a file downloaded from the official BitBox download page.

Include as much of the following information as possible:

• Your Linux distribution and version.
• Whether your system is fully updated.
• Your installation method: .deb, .rpm, or AppImage.
• Whether you use Wayland or X11, if you know.
• Whether your computer is a personal device or a managed work, school, or company device.
• The BitBoxApp version you attempted to install or run.
• The exact package manager, permission, security, or startup error message.
• Whether security software or endpoint protection is installed.
• A screenshot of the warning or error, if possible.

This information helps BitBox Support identify the cause more quickly.