Skip to main content

Python client and library to communicate with Ledger devices

Project description


A Python library to control Ledger devices


This package provides ledgerwallet, a library to interact with Ledger devices, and ledgerctl, a command line tool based on that library to easily perform operations on the devices.

Supported devices are Ledger Blue, Ledger Nano S and Ledger Nano X.

Quick install

ledgerctl and the ledgerwallet library can be installed using pip:

pip3 install --upgrade protobuf setuptools
pip3 install ledgerwallet

Under a Debian or Ubuntu based system, compiling HIDAPI requires to install additional packages:

sudo apt install python3-dev libusb-1.0.0-dev libudev-dev

Device configuration

You should install a custom certificate authority (CA) on the device to make the usage of ledgerctl easier. This certificate is used to establish a custom secure channel between the computer and the device, and identifies ledgerctl as a "trusted manager" on the device.

To install a custom CA, boot the device in "Recovery" mode, by pressing the right button at boot time. Then run:

ledgerctl install-ca <NAME>

where <NAME> is the name that will be displayed on the device to identify the CA. It can be any label, like "ledgerctl", "Dev", or "CA".

You are now ready to use ledgerctl.


To display the commands supported by ledgerctl, run ledgerctl or ledgerctl --help. Help for each command can be displayed by running ledgerctl <command> --help.

Supported commands include retrieving basic device information, installing and removing apps, viewing available space on the device, etc.

Here are a few examples:

  • Displaying available space on the device
ledgerctl meminfo
  • Listing installed applications
ledgerctl list
  • Deleting the Bitcoin application
ledgerctl delete Bitcoin

Installing custom apps

Loading an application on the device is currently bound to the SDK and to the build process.

Installation of custom apps differ from the way provided by the SDK. To keep the install process simple, we chose to use "Manifest" files for applications. Manifests are JSON files which contain the required parameters to install the application. You can find an example manifest in the tests/app directory.

Manifest entries are pretty straightforward if you are familiar with the BOLOS SDK, except one of them: dataSize. That entry specifies the size of the writable area of the application. This is the size needed by the application to save persistent data. Its value seldom changes.

You can use an ugly one-liner to retrieve it:

echo $(($(grep _envram_data debug/ | awk '{ print $1 }') - $(grep _nvram_data debug/ | awk '{ print $1 }')))

As an example, the standard way to install the Bitcoin application you compiled is to run make load with the BOLOS SDK. It launches the following command:

python3 -m ledgerblue.loadApp --curve secp256k1 --tlv --targetId 0x31100004 --targetVersion="1.6.0" --delete --fileName bin/app.hex --appName "Bitcoin" --appVersion 1.3.13 --dataSize $((0x`cat debug/ |grep _envram_data | tr -s ' ' | cut -f2 -d' '|cut -f2 -d'x'` - 0x`cat debug/ |grep _nvram_data | tr -s ' ' | cut -f2 -d' '|cut -f2 -d'x'`)) `ICONHEX=\`python3 /home/dev/sdk/ --hexbitmaponly nanos_app_bitcoin.gif  2>/dev/null\` ; [ ! -z "$ICONHEX" ] && echo "--icon $ICONHEX"`  --path "" --appFlags 0xa50 --offline bin/app.apdu | grep "Application" | cut -f5 -d' ' > bin/app.sha256

To install it with ledgerctl:

  1. Retrieve dataSize using the above one-liner.
  2. Create a manifest file app.json in the ledger-app-btc directory:
    "name": "Bitcoin",
    "version": "1.3.13",
    "icon": "nanos_app_bitcoin.gif",
    "targetId": "0x31100004",
    "flags": "0xA50",
    "derivationPath": {
        "curves": ["secp256k1"]
    "binary": "bin/app.hex",
    "dataSize": 64
  1. Install with ledgerctl install app.json.

If you want to force the deletion of the previous version, run the previous command with the -f flag.

Viewing APDUs

Communication between the host and the device use Application Protocol Data Unit (APDUs). To display the raw APDUs, usually for debugging purposes, run ledgerctl with the -v switch on any command. For example, here are the APDUs exchanged to run the Bitcoin application:

$ ledgerctl -v run Bitcoin
=> e0d8000007426974636f696e
<= 9000

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

ledgerwallet-0.1.2-py3-none-any.whl (26.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page