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.

This guide helps you resolve BitBoxApp installation problems on Linux and open the BitBoxApp successfully.

This article applies if

• The downloaded .deb or .rpm package does not open.
• Your package manager reports an installation error.
• Your Linux system asks for permissions and the installation does not continue.
• The BitBoxApp AppImage does not start.
• Nothing happens when you double-click the BitBoxApp AppImage.
• The BitBoxApp does not open after installation.
• The BitBoxApp still shows an older version after installing the latest version.

Before you continue

Before changing Linux permissions or installing the BitBoxApp again:

1. Delete any BitBoxApp file that was downloaded from an unofficial source.
2. Check the BitBoxApp operating system compatibility article to confirm that your Linux distribution is supported.
3. Install available operating system updates if your Linux system has not been updated recently.
4. Restart your computer if you installed or updated the BitBoxApp but have not restarted Linux yet.

If you want to verify the download before continuing, use the BitBoxApp checksum verification guide. Advanced users can also use the Linux BitBoxApp signature verification guide.

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.
2. Open the official BitBox download page.
3. Download the latest BitBoxApp file for your Linux installation method.
4. Use the .deb package for Debian-based distributions.
5. Use the .rpm package for RPM-based distributions.
6. Use the AppImage if you prefer a portable app file or if your distribution does not use DEB or RPM packages.

The downloaded file should now open normally. If the same issue continues, continue with the section that matches your installation method.

Check your Linux distribution and package type

The BitBoxApp Linux package must match your Linux distribution.

• Use the .deb package on Debian-based distributions such as Debian, Ubuntu, Linux Mint, Pop!_OS, and Zorin OS.
• Use the .rpm package on RPM-based distributions such as Fedora, openSUSE, and Red Hat Enterprise Linux compatible distributions.
• Use the AppImage if your Linux distribution does not support the official DEB or RPM package format.

If you downloaded the wrong package type, delete it and download the correct file from the official BitBox download page.

If your Linux distribution is not supported, the BitBoxApp may fail to install or start correctly. In that case, use a supported distribution or try the AppImage version.

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.

The BitBoxApp should now open normally.

If the package manager continues to report an error, install available operating system updates, download a fresh BitBoxApp package, and try the installation again.

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.

The BitBoxApp AppImage should now start.

If your desktop environment does not show an executable permission option, follow the BitBoxApp AppImage guide for Linux for the terminal-based method.

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.

To check the installed version:

1. Open the BitBoxApp.
2. Open Settings.
3. Open About.
4. Check the displayed BitBoxApp version.

If the old version still appears:

1. Close the BitBoxApp completely.
2. Remove the installed BitBoxApp package or delete the old AppImage file.
3. Download the latest Linux package or AppImage from the official BitBox download page.
4. Install the new package or start the new AppImage.
5. Open Settings.
6. Open About.
7. Check the displayed BitBoxApp version again.

The BitBoxApp should now show the newly installed or newly downloaded version.

If your BitBox is not detected after installation

This article focuses on installing and starting the BitBoxApp on Linux. If the BitBoxApp opens but does not detect your BitBox, follow the BitBox not recognized on Linux troubleshooting guide.

When to contact BitBox support

If none of the steps above resolves the issue, contact BitBox Support through our official Support contact form.

• The BitBoxApp package still does not install.
• The BitBoxApp AppImage still does not start after you made it executable.
• The BitBoxApp still does not open after reinstalling or downloading a fresh file.
• Your Linux system or security software continues to block the BitBoxApp after you confirmed that it was downloaded from the official BitBox download page.
• The BitBoxApp still shows an old version after replacing or reinstalling it.

In your request, 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.
• Any package manager, permission, security, or startup error message.
• Whether security software or endpoint protection is installed.
• Screenshots of the warning or error, if possible.

Providing this information helps BitBox support identify the cause more quickly.

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. The BitBoxApp AppImage guide for Linux explains both the file manager method and the terminal method.

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. 

The BitBoxApp Linux installation guide explains when to use the Linux package, and the BitBoxApp AppImage guide for Linux explains the portable option.

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 BitBoxApp operating system compatibility article 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 BitBox not recognized on Linux troubleshooting guide to check USB detection, udev rules, and permissions.