If the BitBoxApp will not install or open on Linux, start with the message you see. A package-manager error, an AppImage that will not run, and an app that closes immediately need different checks.

Use the section that matches your problem:

• The download is incomplete, or you are unsure which file to use
• A DEB or RPM package will not install
• The AppImage does not start
• Security software or a device policy blocks the file
• The installed BitBoxApp does not open

Check the download and package type

Confirm that you downloaded the file from the official BitBoxApp download page and that the download finished. If the download was interrupted, discard that incomplete file and download a fresh copy. If your browser or security software reports a threat, follow the security-block section before trying again.

The file must match your Linux system. The official Linux downloads are for x86-64 computers, also called amd64; a 64-bit ARM computer needs a different build. Check the supported operating systems before continuing, particularly if you use a distribution or version that is not listed.

• DEB: choose the .deb package for Debian or Ubuntu.
• RPM: choose the .rpm package for Fedora or openSUSE.
• AppImage: choose the .AppImage file to run the app without installing a system-wide package. It still needs a compatible Linux environment.

For the normal procedure, see Install the BitBoxApp on Linux or Run the BitBoxApp AppImage on Linux. Choosing an AppImage does not guarantee compatibility with an unsupported system.

You can check the downloaded file's checksum or verify its signature before running it. If verification fails, do not install or open that file; contact Support.

If a DEB or RPM package fails

Open the correct package with your system's package manager and note the complete error if installation fails. Use that message to choose the next action:

• Wrong package format or architecture: return to the download checks above. Do not force the package to install on an incompatible system.
• Administrator permission required: approve the installation through your system's normal authentication prompt only for the official download. On a managed work or school computer, ask the device administrator if you do not have permission to install software.
• Another installation or update is in progress: let that operation finish, then try the BitBoxApp package again. Do not delete package-manager lock files.
• A missing dependency, package conflict, or another error: record the complete message and contact BitBox Support. Do not force installation or remove system packages to get past the error.

If installation completes, open the BitBoxApp from your applications menu. If it does not open, continue to the startup checks below.

If the AppImage does not start

An AppImage runs directly from the downloaded file. First check that the official file has permission to run:

1. Right-click the AppImage in your file manager and open Properties.
2. Under Permissions or Access Rights, enable the option to run the file as a program. Depending on your file manager, it may be called Allow executing file as program or Is executable.
3. Close Properties and double-click the AppImage again.

If that option is unavailable, use the terminal method in the AppImage guide. If the file still does not open, starting it from a terminal can reveal the error:

1. Open a terminal in the folder containing the downloaded AppImage.
2. Enter the following command, replacing VERSION with the version in your downloaded filename. Keep the quotation marks and the ./ at the beginning.

./"BitBox-VERSION-x86_64.AppImage"

If the BitBoxApp opens, the startup problem is resolved. If the terminal reports a FUSE error, use the next section. For another error, or if no window appears, keep the output and contact Support.

If the error mentions FUSE or libfuse.so.2

Messages such as AppImages require FUSE to run or a missing libfuse.so.2 point to a FUSE library problem. FUSE lets Linux access the contents of the AppImage; making the file executable does not resolve a missing library.

For a missing FUSE 2 library on Ubuntu, install the package for your exact Ubuntu version from its normal repositories:

• Ubuntu 22.04: sudo apt install libfuse2
• Ubuntu 24.04: sudo apt install libfuse2t64

Review the package manager's proposed changes before confirming. If it proposes removing system packages, stop. Do not replace or remove FUSE 3. On another distribution or Ubuntu version, consult the AppImage FUSE troubleshooting documentation or ask your device administrator for the matching package.

After the library installation completes, run the same AppImage again. If the error remains or changes, send the new message to Support rather than repeating the installation.

If security software or a device policy blocks the app

If a browser or security tool reports a threat, quarantines the file, or blocks execution, record the exact warning and any detection name. Do not restore or allow a detected file, disable security protection, or switch download methods to bypass the block. Contact BitBox Support before running it.

On a managed work or school computer, ask the device administrator to review installation or execution restrictions. An AppImage is not a workaround for a managed-device policy.

If the installed BitBoxApp does not open

Use this section if the package manager reports a completed installation but no window appears, or the app closes immediately. Resolve any security warning first.

1. Close any open BitBoxApp window, then try opening the app again.
2. If it still does not open, open a terminal and enter BitBox. The capitalization matters. This is the launcher used by the official DEB and RPM packages.
3. Keep any error output. If the app still does not open, or the terminal reports that the command was not found, contact Support with that result.

Run the app as your normal user. Do not use administrator privileges to work around a startup error, delete BitBoxApp data, or reset your BitBox.

After the BitBoxApp opens

The installation or startup problem is resolved when the BitBoxApp opens normally.

• If it opens but shows an older version, follow the BitBoxApp update guide. You do not need to uninstall the app as a first step.
• If it opens but does not detect your BitBox, follow the Linux device-detection guide for USB permissions and udev rules.

Contact BitBox Support

Contact BitBox Support if the matching checks do not resolve the error, a dependency or package conflict prevents installation, or a security detection remains unresolved. On a managed device, involve the device administrator as well.

Include the information needed to reproduce the problem:

• your Linux distribution, version, and processor architecture, if known;
• the complete downloaded filename and whether you used DEB, RPM, or AppImage;
• whether installation fails or the app fails to open afterward;
• the exact error message, detection name, or relevant terminal output;
• whether the computer is personal or managed by a workplace or school;
• whether you use Wayland or X11, if known; and
• the checks you already tried.

Share only the relevant error or a cropped screenshot, with personal information removed. Never send recovery words, a wallet backup, passwords, passphrases, private keys, or authentication codes.