Python library and command-line client for communicating with Trezor Hardware Wallet.
See https://trezor.io for more information.
Python Trezor tools require Python 3.8 or higher, and libusb 1.0. The easiest
way to install it is with pip. The rest of this guide assumes you have
a working pip; if not, you can refer to this
guide.
On a typical system, you already have all you need. Install trezor with:
pip3 install trezor
On Windows, you also need to either install Trezor Bridge, or libusb and the appropriate drivers.
Current trezorlib version supports Trezor One version 1.8.0 and up, and Trezor T version 2.1.0 and up.
For firmware versions below 1.8.0 and 2.1.0 respectively, the only supported operation is "upgrade firmware".
Trezor One with firmware older than 1.7.0 and bootloader older than 1.6.0 (including pre-2021 fresh-out-of-the-box units) will not be recognized, unless you install HIDAPI support (see below).
Ethereum: To support Ethereum signing from command line, additional packages are needed. Install with:
pip3 install trezor[ethereum]
Stellar: To support Stellar signing from command line, additional packages are needed. Install with:
pip3 install trezor[stellar]
Extended device authentication: For user-friendly device authentication for Trezor
Safe 3 and newer models (trezorctl device authenticate command), additional packages
are needed. Install with:
pip3 install trezor[authentication]
Firmware-less Trezor One: If you are setting up a brand new Trezor One
manufactured before 2021 (with pre-installed bootloader older than 1.6.0), you will
need HIDAPI support. On Linux, you will need the following packages (or their
equivalents) as prerequisites: python3-dev, cython3, libusb-1.0-0-dev,
libudev-dev.
Install with:
pip3 install trezor[hidapi]
To install all four, use pip3 install trezor[hidapi,ethereum,stellar,authentication].
Check out Repology to see if your operating system has an up-to-date python-trezor package.
pip3 install "git+https://github.com/trezor/trezor-firmware#egg=trezor&subdirectory=python"
Install the Poetry tool, checkout
trezor-firmware from git, and enter the poetry shell:
pip3 install poetry
git clone https://github.com/trezor/trezor-firmware
cd trezor-firmware
poetry install
poetry shell
In this environment, trezorlib and the trezorctl tool is running from the live
sources, so your changes are immediately effective.
The included trezorctl python script can perform various tasks such as
changing setting in the Trezor, signing transactions, retrieving account
info and addresses. See the
python/docs/
sub folder for detailed examples and options.
NOTE: An older version of the trezorctl command is available for
Debian Stretch
(and comes pre-installed on Tails OS).
You can use this python library to interact with a Trezor and use its capabilities in your application. See examples here in the tools/ sub folder.
When you are asked for PIN, you have to enter scrambled PIN. Follow the numbers shown on Trezor display and enter the their positions using the numeric keyboard mapping:
| 7 | 8 | 9 |
| 4 | 5 | 6 |
| 1 | 2 | 3 |
Example: your PIN is 1234 and Trezor is displaying the following:
| 2 | 8 | 3 |
| 5 | 4 | 6 |
| 7 | 9 | 1 |
You have to enter: 3795
If you want to change protobuf definitions, you will need to regenerate definitions in
the python/ subdirectory.
First, make sure your submodules are up-to-date with:
git submodule update --init --recursive
Then, rebuild the protobuf messages by running, from the trezor-firmware top-level
directory:
make gen
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
cryptography library). #3364--quality argument to trezorctl set homescreen. #3893trezorctl device self-test command to trezorctl device prodtest-t1. #3504bip39. #3868trezorctl device unlock-bootloader.internal_name field.encrypt-keyvalue / decrypt-keyvalue. #2608trezorctl firmware verify changed order of checks - fingerprint is validated before signatures. #2745trezorctl ethereum sign-tx: renamed --gas-limit shortcut to -G to avoid collision with -t/--token #2535trezorctl fw with unsigned Trezor One firmwares. #2801TrezorClient has a more intelligent UI object. #2832FirmwareType.verify() accepts a parameter configuring whether to use production or development keys. #2701trezorctl --version crash. #1702DeviceIsBusy indicates that the device is in use by another process. #1026normalize_nfc to prepare_message_bytes in tools.py #2126trezorctl monero network type arguments now accept symbolic names instead of numbers. #2219message_hash for domain-only EIP-712 hashes
for Trezor T1 (i.e. when primaryType=EIP712Domain) #2036trezorctl firmware update shows progress bar (Model T only)EndSession #1227init_device(). #1231trezorctl firmware download and trezorctl firmware verify #1258trezorlib.stellar.from_envelope was added, it includes support for the Stellar TransactionV1 format transaction. #1745trezorctl commands. #1783trezorctl ethereum sign-typed-data #1835required fields and default values #379trezorctl firmware-update command changed to trezorctl firmware update #1258btc.sign_tx() accepts keyword arguments for transaction metadata #1266ValueError when the txid for an input is not present in prev_txes during btc.sign_tx #1442trezorlib.mappings was refactored for easier customization #1449UdpTransport.wait_until_ready no longer sets socket to nonblocking #1668trezorlib.stellar will refuse to process transactions containing MuxedAccount #1838details argument to btc.sign_tx() is deprecated. Use keyword arguments instead. #379trezorctl debug show-text functionality #1531tools/build_tx.py to work with Blockbook's API protections. #1896client.init_device(derive_cardano=True) must be used before calling Cardano functions. #1231ui.button_request(x) is changed from int to ButtonRequest.
The original int value can be accessed as x.code #1671trezorlib.stellar was reworked to use stellar-sdk instead of providing local implementations #1745trezorctl btc get-descriptor support #1363trezorctl btc reboot-to-bootloader support #1738attrstools/build_tx.py #1257, #1296trezorlib.toif module (moved from internal) can encode and decode TOIF image formattrezorctl set homescreen was improved and extended to support PNG images for Trezor Ttrezorctl btc get-address #1179trezorctl lisk sign-message--skip-vendor-header from trezorctl firmware-update which did nothing #1210trezorctl set safety-checks controls the new "safety checks" feature. #1126trezorctl btc get-address can create multisig addresses.firmware-update, firmware-upgrade,
update-firmware, upgrade-firmwareTrezorClient.ping() does not crash when device is PIN-lockedtrezorlib.coins, trezorlib.tx_api, and the file coins.json, were removedTrezorClient argument ui is now mandatory. state argument was renamed to session_id.get_passphrase() has a new argument available_on_device.cosi module was changed-P
enforces entering passphrase on host.get-session and option -s allows entering passphrase once
for multiple subsequent trezorctl operationstrezorctl wait-for-emulatortrezorctl debug send-bytes can send raw messages to the device f#116trezorctl list can now show name, model and id of devicetrezorlib.tx_api.json_to_tx was reduced to only support Bitcoin fields, and moved
to trezorlib.btc.from_json.cosi module was streamlined: verify_m_of_n is now verify, the old
verify is verify_combinedget_default_client respects TREZOR_PATH environment variableget_passphrase has an additional argument available_on_device,
indicating that the connected Trezor is capable of on-device entryTransport.write and read method signatures changed to accept bytes instead of
protobuf messages@with_client decorator that manages exception
handling and connecting to devicetrezorlib.tx_api was removedtrezorlib.coins and coin data was removedtrezorlib.ckd_public, which was deprecated in 0.10, was now removed.btc.sign_tx will not preload transaction data from prev_txes, as usage with TxApi
is being removedping() command was removedtrezorlib.clienttrezorlib.tools.CallException was dropped, use trezorlib.exceptions.TrezorFailure insteadtrezorctl device recover supports --u2f-counter option to set the FIDO counter to a custom valuetrezorctl command was reworked for ease of use and maintenance. See trezorctl --help and OPTIONS.rst for details. f#510cleos in delegatebw and undelegatebw actions f#680 f#681RecoveryDevice does not set fields when doing dry-run recovery f#666trezorctl device recover f#778docs/transaction-format.md
for details.trezorctl firmware-update, the new --beta switch enables downloading beta
firmwares. By default, only stable firmware is used. f#411, f#420trezorctl firmware-update, the new --bitcoin-only switch enables downloading
Bitcoin-only firmwaresrc subdirectory contains sources and
tests subdirectory contains tests, so that cwd is not clutteredtrezorctl script was moved into a module trezorlib.cli.trezorctl and is launched
through the entry_points mechanism. This makes it usable on Windowspyblake2 is no longer required on Python 3.6 and upclear_session the client also forgets the passphrase state for TT f#525dict_to_proto now allows enum values as stringsprotoc is no longer required.get_default_client for simple script usagenetwork to protocol_magicINTERACT=1 environment variable is setto_dict functionsign-tx is considered deprecatedTrezorClient and UI handling. Implementers must now provide a "UI" object instead of overriding callbacks #307, #314get_fields() method instead of FIELDS field #312TrezorClient class are now in separate modules and take a TrezorClient instance as argument #276TrezorClient anymoreTrezorClientDebugLink was moved to debuglink moduletrezorlib.btc.sign_tx@field decorator was replaced by an argument to @expectprotobuf.dict_to_proto can create a protobuf instance from a plain dicttx_api now supports Blockbook backend serversTxApiInsight is just TxApidevice.reset and device.recover now have reasonable defaults for all argumentsset_tx_api method on TrezorClient is replaced by an argument for sign_txTxApi was moved to a separate test-support classEncryptMessage and DecryptMessage actions are goneTrezorClient can now detect when a HID device is removed and a different one is plugged in on the same path_" and "-" as same in command names #314stellar_get_address and _public_key functions support show_display parameterstellar_get_address and _public_key commands for the respective functionalitylist_coins is removed because we no longer parse the relevant protobuf field
(and newer Trezor firmwares don't send it) #277ckd_public module would fail #280TrezorClient takes an additional argument state that allows reusing the previously entered passphrase #241log.enable_debug_output function turns on wire logging, instead of having to use TrezorClientVerbose123h in addition to 123' to indicate hardening-p now supports prefix search for device path #226transport submoduletrezor-common repository #248ed25519raw to _ed25519 to indicate its privatenessed25519cosi to cosi and expanded its APIlogging facility instead of custom printing through VerboseWireMixinclient.format_protobuf is moved to protobuf.format_messagetools.Hash is renamed to tools.btc_hashcoins module coins_txapi is renamed to tx_api.
coins_slip44 is renamed to slip44.TREZOR_PATH env variable.-vxfailed tests selectively based on pytest.inickd_public is only maintained in tests.support submodule and considered privateTrezorClient.expand_path is moved to plain function tools.parse_pathTrezorDevice is deprecated in favor of transport.enumerate_devices and transport.get_transporttools is slated for removalTrezorClientVerbose and VerboseWireMixin is removedtx_api.TxApi* classes removed in favor of coins.tx_apiclient.PRIME_DERIVATION_FLAG is removed in favor of tools.HARDENED_FLAG and tools.H_()trezor[hidapi] or trezor[ethereum] to get them.sign_tx operation sending empty address string #237trezorctl:
TREZOR_PATH environment variable to preselect a Trezor device.FAQs
Python library for communicating with Trezor Hardware Wallet
We found that trezor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.