Ledger Nano (Original) Python Library

0.1.32 · abandoned · verified Thu Apr 16

This library provides Python utilities to communicate with the *original* Ledger Nano hardware wallet over USB HID. It is specific to the first generation of Ledger devices and is largely superseded by `ledger-python` and `ledgerblue` for modern Ledger Nano S, X, and Stax devices. The current version is 0.1.32, with no active development since 2017, indicating an abandoned status.

Common errors

```
ImportError: cannot import name 'DongleUSB' from 'btchip.btchipComm'
```
cause The `btchip-python` library is not installed, or the import path is incorrect.

fix Ensure the package is installed: `pip install btchip-python`. Verify the import statement matches `from btchip.btchipComm import DongleUSB`.
```
btchip.btchipComm.DongleUSB.DongleNotFoundException: No dongle found
```
cause The original Ledger Nano is not connected, or USB HID permissions are insufficient for your user, or you are trying to use it with a modern Ledger device.

fix Connect the original Ledger Nano. On Linux, ensure `hidapi` system dependencies are installed and udev rules are correctly configured (refer to Ledger's setup guides for `ledgerblue` or `ledger-python` for applicable udev rule examples). Confirm you are using an *original* Ledger Nano, not a Nano S/X/Stax.
```
hidapi.hid.HIDException: failed to open device
```
cause Similar to 'No dongle found', this indicates `hidapi` could not access the device, often due to missing `libusb` or insufficient permissions.

fix Ensure `libusb` (and `libudev-dev` on Linux) are installed via your system's package manager, then reinstall `hidapi` (`pip install --no-cache-dir --force-reinstall hidapi`). Confirm udev rules for Ledger devices are correctly applied on Linux and that your user is part of the `plugdev` group.

Warnings

breaking This library is designed exclusively for the *original* Ledger Nano hardware wallet. It is NOT compatible with modern Ledger Nano S, Nano X, or Stax devices. Using it with newer devices will result in 'No dongle found' errors or incorrect behavior.
Fix: For Ledger Nano S/X/Stax, use the actively maintained `ledger-python` library (PyPI: `ledger-app-builder`) or `ledgerblue` for device communication.
deprecated The `btchip-python` library has been abandoned since its last update in 2017. It receives no further development or security updates. Its functionality is largely superseded by newer Ledger-supported libraries.
Fix: Migrate to `ledger-python` or `ledgerblue` for any new development or maintenance involving Ledger hardware, especially for modern devices.
gotcha Successful device communication requires the `hidapi` library and proper system-level USB HID permissions, particularly on Linux (e.g., udev rules). Without these, the library will fail to detect the device.
Fix: Install `hidapi`'s system dependencies (e.g., `libusb-1.0-0-dev` on Debian/Ubuntu, `hidapi-devel` on Fedora, `libusb` on macOS) before `pip install hidapi`. On Linux, add udev rules for Ledger devices (e.g., `SUBSYSTEM=="usb", ATTR{idVendor}=="2c97", MODE="0660", GROUP="plugdev", TAG+="uaccess"`).
gotcha The `getFirmwareVersion()` method returns a `BtchipFirmware` object, which, when converted to a string, includes both the version and a status word (e.g., '0.1.0 9000'). Extracting only the version number requires parsing.
Fix: Access the string representation and parse it, e.g., `str(firmware_object).split(' ')[0]` to get just the version number.

Install

pip install btchip-python Install btchip-python
sudo apt-get update && sudo apt-get install -y libusb-1.0-0-dev libudev-dev pip install hidapi Linux: Install hidapi system dependencies (required for btchip-python)
brew install libusb pip install hidapi macOS: Install hidapi system dependencies (required for btchip-python)

Imports

DongleUSB
```
from btchip.btchipComm import DongleUSB
```
The communication backend for USB HID.
btchip
```
from btchip.btchip import btchip
```
The main interface class for sending commands to the device.

Quickstart

Demonstrates connecting to an original Ledger Nano and retrieving its firmware version. This example highlights the specific hardware compatibility and common setup requirements.

from btchip.btchipComm import DongleUSB
from btchip.btchip import btchip

# NOTE: This library is for the *original* Ledger Nano hardware wallet,
# NOT for Ledger Nano S/X/Stax. For modern devices, use 'ledger-python'.
#
# Requires the original Ledger Nano to be connected and proper USB HID
# permissions (e.g., udev rules on Linux).

dongle = None
try:
    # Initialize the USB dongle communication (timeout in ms)
    # DongleUSB() without args tries to autodetect original Nano.
    dongle = DongleUSB(timeout=5000)
    
    # Initialize the btchip interface with the dongle
    interface = btchip(dongle)
    
    # Example: Get firmware version
    firmware_version_response = interface.getFirmwareVersion()
    # getFirmwareVersion returns a BtchipFirmware object, which __str__ outputs 'VERSION_STRING STATUS_WORD'
    firmware_version = str(firmware_version_response).split(' ')[0] # Extract only the version string
    
    print(f"Successfully connected to original Ledger Nano.")
    print(f"Device Firmware Version: {firmware_version}")
    
except Exception as e:
    print(f"Failed to connect to original Ledger Nano: {e}")
    print("\nTroubleshooting:")
    print("- Ensure the original Ledger Nano is connected.")
    print("- On Linux, ensure appropriate udev rules are in place for Ledger HID devices.")
    print("- Verify 'hidapi' is correctly installed with its system dependencies.")
    print("- Remember: This library does NOT work with Ledger Nano S/X/Stax.")
finally:
    if dongle:
        dongle.close()

view raw JSON →