Table of Contents

Before you start Quick checks Check whether Linux detects your BitBox If Linux does not detect the BitBox If Linux detects the BitBox, but the BitBoxApp does not Recommended approach: install udev rules with the official script Manual approach: install udev rules yourself If the BitBox is still not detected in the BitBoxApp Check for conflicting software Still having problems? FAQ – Frequently asked questions Is my BitBox defective if it is not recognized on Linux? Why does Linux detect my BitBox, but the BitBoxApp does not? What are udev rules? What does 03eb:2403 mean? Do I need to reboot after installing udev rules? Can I lose my coins because of a USB connection issue? When should I contact support?

If your BitBox is not detected by the BitBoxApp on Linux, the issue is often related to USB access permissions.

Linux may detect the BitBox correctly, but the BitBoxApp may still be unable to communicate with it if the required udev rules are missing.

This guide helps you check whether Linux detects your BitBox and explains how to install the required udev rules.

This article is for Linux users. If you use macOS or Windows, follow the dedicated guide for your operating system.

 

Before you start

Before troubleshooting your USB connection, make sure that:

Outdated BitBoxApp or firmware versions can prevent the BitBox from being detected correctly, even if Linux detects the USB device.

 

Quick checks

Start with these basic checks before changing Linux permissions or system configuration.

  1. Try a different USB cable.
  2. Connect the BitBox directly to your computer.
  3. Avoid USB hubs, docking stations, adapters, or extension cables during troubleshooting.
  4. Try a different USB port.
  5. Connect the BitBox so that the screen is facing up.
  6. Restart your computer.
  7. Test the BitBox on another computer or Android smartphone, if possible.

If the BitBox works on another device, the BitBox itself is most likely working correctly. The issue is probably related to your Linux system, USB permissions, distribution setup, or software configuration.

 

Check whether Linux detects your BitBox

First, check whether Linux recognizes the BitBox as a connected USB device.

  1. Connect your BitBox to your Linux computer.
  2. Open a terminal.
  3. Run:
lsusb
  1. Look for an entry containing BitBox or the vendor and product ID:
03eb:2403

If the output includes 03eb:2403, Linux detects your BitBox.

The lsusb command checks whether Linux detects the device at the USB level. It does not confirm that the BitBoxApp has permission to communicate with it.

 

If Linux does not detect the BitBox

If lsusb does not show 03eb:2403 or any BitBox-related entry, Linux does not currently detect the device.

In this case, repeat the physical connection checks carefully:

  1. Use a different USB cable.
  2. Remove any USB hub, dock, adapter, or extension cable.
  3. Try another USB port.
  4. Restart your computer.
  5. Test the BitBox on another computer or Android smartphone, if possible.

If the BitBox is not detected on any device, contact support and include the steps you already tried.

If Linux detects the BitBox, but the BitBoxApp does not

If lsusb shows 03eb:2403, Linux detects the BitBox. If the BitBoxApp still does not show it, the issue is usually related to missing USB access permissions.

On Linux, this is solved by installing the correct udev rules.

There are two ways to install the rules:

  • Recommended: install them with the official GitHub script.
  • Manual: create the udev rules yourself.

The following steps change system-level Linux configuration. Continue only if you are comfortable using the terminal.

 

This is the recommended approach for most users because it reduces the risk of manual errors.

The script:

  • installs the correct udev rules,
  • uses the official filenames and rule definitions,
  • matches the setup used by distribution packages,
  • and is easier to maintain than a manual setup.

Download and run the official udev rules script from the BitBox GitHub repository:
→ frontends/qt/resources/deb-afterinstall.sh

After running the script:

  1. Unplug your BitBox.
  2. Reconnect your BitBox.
  3. Restart the BitBoxApp.
  4. Log out and log back in, or reboot your computer if required.

This is the recommended approach for most Linux users. It is easier to maintain and less error-prone than manually creating udev rules.

 

Manual approach: install udev rules yourself

Use this approach only if you prefer full control or cannot run the official script.

  1. Open a terminal.
  2. Create the first udev rule:
sudo tee /etc/udev/rules.d/53-hid-BitBox.rules > /dev/null <<EOF
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2403", TAG+="uaccess", TAG+="udev-acl"
EOF
  1. Create the second udev rule:
sudo tee /etc/udev/rules.d/54-hidraw-BitBox.rules > /dev/null <<EOF
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2403", TAG+="uaccess", TAG+="udev-acl"
EOF
  1. Reload the udev rules:
sudo udevadm control --reload
  1. Apply the udev rules:
sudo udevadm trigger
  1. Unplug your BitBox.
  2. Reconnect your BitBox.
  3. Restart the BitBoxApp.

If the BitBox is still not detected in the BitBoxApp

On some Linux distributions, additional group permissions may be required.

  1. Add your user to the plugdev group:
sudo usermod -aG plugdev $USER
  1. Log out and log back in, or reboot your computer.
  2. Reconnect your BitBox.
  3. Restart the BitBoxApp.

Group changes only take effect after logging out and back in, or after restarting the computer.

 

Check for conflicting software

Some software can interfere with USB device detection or communication. This can include:

  • security software,
  • firewall tools,
  • endpoint security tools,
  • virtualization tools,
  • remote desktop tools,
  • enterprise device management software,
  • or other software that controls USB access.

If you use a work-managed computer, USB access may be restricted by your organization.

In that case, test your BitBox on a personal computer if possible.

Still having problems?

If your BitBox is still not recognized after completing the steps above, our support team will be happy to help.

Please include the following information:

  • your Linux distribution and version,
  • the BitBoxApp version you are using,
  • whether lsusb shows 03eb:2403,
  • whether you installed the udev rules using the script or manually,
  • whether you logged out and back in or rebooted,
  • what you have already tried,
  • and your BitBoxApp log files.

You can follow this guide to export the required files:
How to locate and export BitBoxApp support files 

Then contact support and include the information above.

If you reached this point, you have already completed the standard Linux troubleshooting steps. This information helps support investigate the issue more specifically.

 

FAQ – Frequently asked questions

Is my BitBox defective if it is not recognized on Linux?

In most cases, no. USB connection issues are usually caused by cables, USB ports, adapters, missing udev rules, permissions, or Linux system configuration.

Why does Linux detect my BitBox, but the BitBoxApp does not?

If lsusb shows 03eb:2403, Linux detects the BitBox at the USB level. If the BitBoxApp still does not show it, the required USB access permissions are usually missing.

What are udev rules?

udev rules are Linux system rules that define how connected devices are handled. For the BitBox, they allow the BitBoxApp to communicate with the device over USB.

What does 03eb:2403 mean?

03eb:2403 is the USB vendor and product ID used to identify the BitBox. If lsusb shows this value, Linux detects your BitBox.

Do I need to reboot after installing udev rules?

Usually, unplugging and reconnecting the BitBox and restarting the BitBoxApp is enough. If the BitBox is still not detected, log out and back in, or reboot your computer.

Can I lose my coins because of a USB connection issue?

No. Your coins are not stored on the BitBox. They are recorded on the blockchain. As long as your recovery words are safely backed up, your funds are not at risk because of a USB connection issue.

When should I contact support?

Contact support if you have tried different cables, ports, and devices, checked lsusb, installed the udev rules, restarted your session or computer, and the issue still persists.

Related Articles

Was this article helpful?

Give feedback about this article