Issues Encountered When Sideloading Ledger Device Apps on Emulator and Real Device

Wed, 15 Apr 2026 10:54:59 +0800

Ledger is arguably the No.1 in the hardware wallet niche, but I still ran into quite a few issues during actual use - through Discord, Twitter, email, official docs, and direct communication. I hit many pitfalls along the way, so here is a summary to help other developers avoid the same traps.

Notes

The models I actually used are the Nano S Plus and Nano X. Note that the X does not support sideloading.
For a comprehensive introduction to Ledger, see Ledger Device App Development Guide. I won’t repeat that here.

Real Device Sideloading

Sideloading Device Compatibility

Not all Ledger models support real device sideloading, as mentioned above. How can you check which models are supported?

Check the official website.
Use the official VS Code extension - Ledger Dev Tools. If you select a specific device, you can tell from whether the sideload button is enabled or disabled.

Sideloading Runtime Environment

Official VS Code extension - Ledger Dev Tools
- There are many extensions matching the “ledger” keyword, so make sure you install the right one.
Docker must be installed and kept running.
- Follow the official guide to install Docker. On Mac, the desktop app installation is recommended.
When you first open the extension, it will pull the ledger-app-dev-tools image and start the container. The image size is approximately 8.51GB.

docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools

Sideloading Test Operating Systems

Ubuntu and other Linux distributions
macOS
Windows - this is probably the hardest to set up.

On Ubuntu, do not use the snap-installed version of Docker. Install it directly from the official website instead, otherwise you will run into permission issues that prevent sideloading from working properly.

macOS

If you just want to verify connectivity, run the following:

pip install ledgerblue

from ledgerblue.comm import getDongle
from ledgerblue.commException import CommException

try:
 dongle = getDongle(debug=True)
 # GET VERSION APDU on the dashboard
 result = dongle.exchange(bytes.fromhex("e001000000"))
 print("Connected! Response:", result.hex())
 dongle.close()
except CommException as e:
 print(f"APDU error (SW=0x{e.sw:04X}): {e.message}")
except Exception as e:
 print(f"Unable to connect: {e}")

Final Thoughts

Overall, while Ledger Device App sideloading provides a great testing environment, there are still some issues and limitations in practice. I hope this article helps developers better understand and resolve these problems, improving both development efficiency and user experience.

Sideloading | Attack on Life

Issues Encountered When Sideloading Ledger Device Apps on Emulator and Real Device