Package: trezor
trezorlibPython library and command-line client for communicating with Trezor
Hardware Wallet.Seehttps://trezor.iofor more information.InstallPython Trezor tools require Python 3.6 or higher, and libusb 1.0. The easiest
way to install it is withpip. The rest of this guide assumes you have
a workingpip; if not, you can refer tothis
guide.On a typical system, you already have all you need. Installtrezorwith:pip3installtrezorOn Windows, you also need to either installTrezor Bridge, orlibusband the appropriatedrivers.Firmware version requirementsCurrent 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 firmwareolder than 1.7.0and bootloaderolder than 1.6.0(including pre-2021 fresh-out-of-the-box units) will not be recognized, unless
you install HIDAPI support (see below).Installation optionsEthereum: To support Ethereum signing from command line, additional packages are
needed. Install with:pip3installtrezor[ethereum]Stellar: To support Stellar signing from command line, additional packages are
needed. Install with:pip3installtrezor[stellar]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:pip3installtrezor[hidapi]To install all three, usepip3 install trezor[hidapi,ethereum,stellar].Distro packagesCheck outRepologyto see if your
operating system has an up-to-date python-trezor package.Installing latest version from GitHubpip3install"git+https://github.com/trezor/trezor-firmware#egg=trezor&subdirectory=python"Running from sourceInstall thePoetrytool, checkouttrezor-firmwarefrom git, and enter the poetry shell:pip3installpoetry
gitclonehttps://github.com/trezor/trezor-firmwarecdtrezor-firmware
poetryinstall
poetryshellIn this environment, trezorlib and thetrezorctltool is running from the live
sources, so your changes are immediately effective.Command line client (trezorctl)The includedtrezorctlpython script can perform various tasks such as
changing setting in the Trezor, signing transactions, retrieving account
info and addresses. See thepython/docs/sub folder for detailed examples and options.NOTE: An older version of thetrezorctlcommand isavailable for
Debian Stretch(and comes pre-installed onTails OS).Python LibraryYou can use this python library to interact with a Trezor and use its capabilities in
your application. See examples here in thetools/sub folder.PIN EnteringWhen 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:789456123Example: your PIN is1234and Trezor is displaying the following:283546791You have to enter:3795ContributingIf you want to change protobuf or coin definitions, you will need to regenerate
definitions in thepython/subdirectory.First, make sure your submodules are up-to-date with:gitsubmoduleupdate--init--recursiveThen, rebuild the protobuf messages by running, from thetrezor-firmwaretop-level
directory:makegenTo get support for BTC-like coins, these steps are enough and no further
changes to the library are necessary.ChangelogAll notable changes to this project will be documented in this file.The format is based onKeep a Changelog,
and this project adheres toSemantic Versioning.0.13.8(2023-10-19)AddedAdded full support for Trezor Safe 3 (T2B1).Added support for STM32F429I-DISC1 board#2989Add support for address chunkification in Receive and Sign flow.#3237Implement device authenticate command.#3255trezorctl: support unlocking bootloader viatrezorctl device unlock-bootloader.ChangedUse 'h' character for hardened BIP-32 components in help texts.#3037trezorctl: Use 'h' character in generated descriptors.#3037ClickUI: notify user in terminal that they should enter PIN or passphrase on Trezor.#3203Internal names are used consistently in constants and names. Original model-based names are kept as aliases for backwards compatibility.Trezor model detection will try to use theinternal_namefield.FixedDrop simple-rlp dependency and use internal copy#3045Fixed printing Trezor model when validating firmware image#3227Corrected vendor header signing keys for Safe 3 (T2B1).0.13.7(2023-06-02)AddedRecognize signing keys for T2B1.Add possibility to call tutorial flow#2795Add ability to change homescreen for Model R#2967Recognize hw model field in vendor headers.#30480.13.6(2023-04-24)AddedSigned Ethereum network and token definitions from host#15Support SLIP-25 in get-descriptor.#2541trezorctl: Support prompt configuration forencrypt-keyvalue/decrypt-keyvalue.#2608Support for external reward addresses in Cardano CIP-36 registrations#2692Auto-convert image to Trezor's homescreen format.#2880Changedtrezorctl firmware verifychanged order of checks - fingerprint is validated before signatures.#2745FixedRemoved attempt to initialize the device after wipe in bootloader mode#2221Limit memory exhaustion in protobuf parser.#2439trezorctl ethereum sign-tx: renamed--gas-limitshortcut to-Gto avoid collision with-t/--token#2535Fixed behavior of UDP transport search by path when full path is provided and prefix_search is True#2786Fixed behavior oftrezorctl fwwith unsigned Trezor One firmwares.#2801Improve typing information whenTrezorClienthas a more intelligent UI object.#2832When enabling passphrase force-on-device, do not also prompt to enable passphrase if it is already enabled.#28330.13.5(2022-12-28)AddedAdd support for model field in firmware image.#2701Add support for v3-style Trezor One signatures.#2701ChangedMore structured information about signing keys for different models.#2701Incompatible changesInstead of accepting a list of public keys,FirmwareType.verify()accepts a parameter configuring whether to use production or development keys.#27010.13.4(2022-11-04)AddedAdd UnlockPath message.#2289Added new TOI formats - little endian full-color and even-high grayscale#2414Add device set-busy command to trezorctl.#2445Support SLIP-25 accounts in get-public-node and get-address.#2517Add possibility to save emulator screenshots.#2547Support for Cardano CIP-36 governance registration format#2561RemovedRemove DATA parameter from trezorctl cosi commit.Remove firmware dumping capability.#2433FixedFixed issue where type declarations were not visible to consumer packages.#2542Incompatible changesRefactored firmware parsing and validation to a more object oriented approach.#25760.13.3(2022-07-13)AddedSupport for Cardano Babbage era transaction items#2354FixedFix Click 7.x compatibility.#23640.13.2(2022-06-30)FixedFixed dependency error when running trezorctl without PIL.Fixed dependency error when running trezorctl on Python 3.6 without rlp.Fixtrezorctl --versioncrash.#17020.13.1(2022-06-29)AddedNew exception typeDeviceIsBusyindicates that the device is in use by another process.#1026Support payment requests and GetNonce command.#1430Add press_info() to DebugLink.#1430Add support for blind EIP-712 signing for Trezor One#1970Add ScriptUI for trezorctl, spawned by --script option#2023Support T1 screenshot saving in Debuglink#2093Support generating Electrum-compatible message signatures in CLI.#2100Support Cardano Alonzo-era transaction items and --include-network-id flag#2114trezorctl: Bitcoin commands can detect script type from derivation path.#2159Add support for model R#2230Add firmware get-hash command.#2239Jump and stay in bootloader from firmware through SVC call reverse trampoline.#2284ChangedUnify boolean arguments/options in trezorlib commands to on/off#2123Renamenormalize_nfctoprepare_message_bytesin tools.py#2126trezorctl moneronetwork type arguments now accept symbolic names instead of numbers.#2219Fixedtrezorctl will correctly report that device is in use.#1026Allow passing emptymessage_hashfor domain-only EIP-712 hashes
for Trezor T1 (i.e. whenprimaryType=EIP712Domain)#2036Fixed error when printing protobuf message with a missing required field.#2135Add compatibility with Click 8.1#21990.13.0- 2021-12-09Addedtrezorctl firmware updateshows progress bar (Model T only)Enabled session management viaEndSession#1227Added parameters to enable Cardano derivation when callinginit_device().#1231two new trezorctl commands -trezorctl firmware downloadandtrezorctl firmware verify#1258Support no_script_type option in SignMessage.#1586Support for Ethereum EIP1559 transactions#1604Debuglink can automatically scroll through paginated views.#1671Support for Taproot descriptors#1710trezorlib.stellar.from_envelopewas added, it includes support for the StellarTransactionV1format transaction.#1745Ethereum: support 64-bit chain IDs#1771Support for Cardano multi-sig transactions, token minting, script addresses, multi-sig keys, minting keys and native script verification#1772Added parameters to specify kind of Cardano derivation to all functions andtrezorctlcommands.#1783Support for EIP-712 in library andtrezorctl ethereum sign-typed-data#1835Add script_pubkey field to TxInput message.#1857Full type hinting checkable with pyright#1893Changedprotobuf is aware ofrequiredfields and default values#379trezorctl firmware-updatecommand changed totrezorctl firmware update#1258btc.sign_tx()accepts keyword arguments for transaction metadata#1266RaiseValueErrorwhen the txid for an input is not present inprev_txesduringbtc.sign_tx#1442trezorlib.mappingswas refactored for easier customization#1449Refactor protobuf codec for better clarity#1541UdpTransport.wait_until_readyno longer sets socket to nonblocking#1668Cardano transaction parameters are now streamed into the device one by one instead of being sent as one large object#1683trezorlib.stellarwill refuse to process transactions containing MuxedAccount#1838Use unified descriptors format.#1885Introduce Trezor models as an abstraction over USB IDs, vendor strings, and possibly protobuf mappings.#1967Deprecatedinstantiating protobuf objects with positional arguments is deprecated#379detailsargument tobtc.sign_tx()is deprecated. Use keyword arguments instead.#379values of required fields must be supplied at instantiation time. Omitting them is deprecated.#379Removeddropped Python 3.5 support#810dropped debug-onlytrezorctl debug show-textfunctionality#1531Removed support for Lisk#1765Fixedfix operator precedence issue for ethereum sign-tx command#1867Updatedtools/build_tx.pyto work with Blockbook's API protections.#1896Fix PIN and passphrase entry in certain terminals on Windows#1959Incompatible changesclient.init_device(derive_cardano=True)must be used before calling Cardano functions.#1231The type of argument toui.button_request(x)is changed from int to ButtonRequest.
The original int value can be accessed asx.code#1671Due to transaction streaming in Cardano, it isn't possible to return the whole serialized transaction anymore. Instead the transaction hash, transaction witnesses and auxiliary data supplement are returned and the serialized transaction needs to be assembled by the client.#1683trezorlib.stellarwas reworked to use stellar-sdk instead of providing local implementations#1745Cardano derivation now defaults to Icarus method. This will result in different keys for users with 24-word seed.#17830.12.4- 2021-09-07Fixedtrezorctl: fixed "Invalid value for " when using Click 8 and param is not specified#17980.12.3- 2021-07-29Addedtrezorctl btc get-descriptorsupport#1363trezorctl btc reboot-to-bootloadersupport#1738distinguishing between temporary and permanent safety checkstrezorctl accepts PIN entered by letters (useful on laptops)support for 50-digit PIN for T1Changedallowed Click 8.x as a requirementreplaced all references to Trezor Wallet with Trezor Suite, and modified all mentions
of Beta WalletFixedadded missing requirementattrsproperly parse big numbers intools/build_tx.py#1257,#1296it is now possible to set safety checks for T10.12.2- 2020-08-27Addedtrezorlib.toifmodule (moved from internal) can encode and decode TOIF image formattrezorctl set homescreenwas improved and extended to support PNG images for Trezor TChangedtrezorctl will correctly notify the user if the image decoding library is missingFixedfix exception intrezorctl btc get-address#1179fix exception intrezorctl lisk sign-messagefix exception in trezorctl commands that accept filenames#1196fix "Invalid homescreen" error when un-setting homescreenRemovedremoved option--skip-vendor-headerfromtrezorctl firmware-updatewhich did nothing#12100.12.1- 2020-08-05Addedtrezorctl set safety-checkscontrols the new "safety checks" feature.#1126trezorctl btc get-addresscan create multisig addresses.the following commands are now equivalent in trezorctl:firmware-update,firmware-upgrade,update-firmware,upgrade-firmwaresupport for EXTERNAL input type#38,#1052support for ownership proofssupport for pre-authorized CoinJoin transactions#37support for Cardano Shelley#948Changeddo not allow setting auto-lock delay unless PIN is configuredFixedcorrectly calculate hashes for very small firmwaresf#1082unified file arguments in trezorctlTrezorClient.ping()does not crash when device is PIN-locked0.12.0- 2020-04-01Incompatible changestrezorlib.coins,trezorlib.tx_api, and the filecoins.json, were removedTrezorClientargumentuiis now mandatory.stateargument was renamed tosession_id.UI callbackget_passphrase()has a new argumentavailable_on_device.API forcosimodule was changedother changes may also introduce incompatibilities, please review the full list belowAddedsupport for firmwares 1.9.0 and 2.3.0Model T now defaults to entering passphrase on device. New trezorctl option-Penforces entering passphrase on host.support for "passphrase always on device" mode on model Tnew trezorctl commandget-sessionand option-sallows entering passphrase once
for multiple subsequent trezorctl operationsbuilt-in functionality of UdpTransport to wait until an emulator comes up, and the
related commandtrezorctl wait-for-emulatortrezorctl debug send-bytescan send raw messages to the devicef#116when updating firmware, user is warned that the requested version does not match their devicef#823trezorctl listcan now show name, model and id of deviceChangedtrezorlib.tx_api.json_to_txwas reduced to only support Bitcoin fields, and moved
totrezorlib.btc.from_json.API forcosimodule was streamlined:verify_m_of_nis nowverify, the oldverifyisverify_combinedinternals of firmware parsing were reworked to support signing firmware headersget_default_clientrespectsTREZOR_PATHenvironment variableUI callbackget_passphrasehas an additional argumentavailable_on_device,
indicating that the connected Trezor is capable of on-device entryTransport.writeandreadmethod signatures changed to accept bytes instead of
protobuf messagestrezorctl subcommands have a common@with_clientdecorator that manages exception
handling and connecting to deviceFixedtrezorctl does not print empty line when there is no outputtrezorctl cleanly reports wire exceptionsf#226Removedtrezorlib.tx_apiwas removedtrezorlib.coinsand coin data was removedtrezorlib.ckd_public, which was deprecated in 0.10, was now removed.btc.sign_txwill not preload transaction data fromprev_txes, as usage with TxApi
is being removedPIN protection and passphrase protection forping()command was removedcompatibility no-op code from trezorlib 0.9 was removed fromtrezorlib.clienttrezorlib.tools.CallExceptionwas dropped, usetrezorlib.exceptions.TrezorFailureinstead0.11.6- 2019-12-30Addedsupport for get-and-increase FIDO counter operationsupport for setting wipe codetrezorctl device recoversupports--u2f-counteroption to set the FIDO counter to a custom valueChangedtrezorctlcommand was reworked for ease of use and maintenance. Seetrezorctl --helpandOPTIONS.rstfor details.f#510updated EOS transaction parser to matchcleosindelegatebwandundelegatebwactionsf#680f#681RecoveryDevicedoes not set fields when doing dry-run recoveryf#666Fixedfixed "expand words" functionality intrezorctl device recoverf#778Removedtrezorctl no longer interactively signs Bitcoin-like transactions, the only allowed
input format is JSON. Seedocs/transaction-format.mdfor details.support for "load device by xprv" was removed from firmware and trezorlib0.11.5- 2019-09-26Addedtrezorctl can dump raw protobuf bytes in debug outputf#117trezorctl shows a warning when activating Shamir Backup if the device does not support itf#445warnings are emitted when encountering unknown value for a protobuf enumf#363debug messages show enum value names instead of raw numberssupport for packed repeated encoding in the protobuf decoderintrezorctl firmware-update, the new--betaswitch enables downloading beta
firmwares. By default, only stable firmware is used.f#411,f#420intrezorctl firmware-update, the new--bitcoin-onlyswitch enables downloading
Bitcoin-only firmwaresupport for FIDO2 resident credential managementsupport for SD-protect featuresChangedpackage directory structure was changed:srcsubdirectory contains sources andtestssubdirectory contains tests, so that cwd is not clutteredtrezorctlscript was moved into a moduletrezorlib.cli.trezorctland is launched
through theentry_pointsmechanism. This makes it usable on Windowspyblake2is no longer required on Python 3.6 and upinput flows can only be used in with-block (only relevant for unit tests)if not specified, trezorctl will set label to "SLIP-0014" in SLIP-0014 modeinclear_sessionthe client also forgets the passphrase state for TTf#525Fixedtrezorctl will properly check if a firmware is present on a new T1f#224Removeddevice test suite was moved out of trezor package0.11.4- 2019-07-31Addedtrezorctl support for SLIP-39 Shamir Backupsupport for Binance Chain0.11.3- 2019-05-29Addedtrezorctl can now send ERC20 tokenstrezorctl usb-reset will perform USB reset on devices in inconsistent stateset-display-rotation command added for TT firmware 2.1.1EOS supportf#87Tezos: add voting supportf#41dict_to_protonow allows enum values as stringsChangedMinimum firmware versions bumped to 1.8.0 and 2.1.0Cleaner errors when UI object is not suppliedGenerated files are now part of the source tarball again. That means thatprotocis no longer required.FixedEthereum commands in trezorctl now workMemory debugging tools now work againRemovedTron and Ontology support removed until implementations exist in Trezor firmware0.11.2- 2019-02-27Addedfull support for bootloader 1.8.0 and relevant firmware upgrade functionalitytrezorctl: support fully offline signing JSON-encoded transaction datatrezorctl: dry-run for firmware upgrade commandclient: new convenience functionget_default_clientfor simple script usageDash: support DIP-2 special inputs#351Ethereum: add get_public_key methodsChangedcoins with BIP-143 fork id (BCH, BTG) won't require prev_tx#352device recovery will restore U2F counterCardano: changenetworktoprotocol_magictests can run interactively whenINTERACT=1environment variable is setprotobuf: improvedto_dictfunctionDeprecatedtrezorctl: interactive signing withsign-txis considered deprecated0.11.1- 2018-12-28Fixedcrash when entering passphrase on device with Trezor TQt widgets should only import QtCore#3490.11.0- 2018-12-06Incompatible changesremoved support for Python 3.3 and 3.4major refactor ofTrezorClientand UI handling. Implementers must now provide a "UI" object instead of overriding callbacks#307,#314protobuf classes now use aget_fields()method instead ofFIELDSfield#312all methods onTrezorClientclass are now in separate modules and take aTrezorClientinstance as argument#276mixin classes are also removed, you are not supposed to extendTrezorClientanymoreTrezorClientDebugLinkwas moved todebuglinkmodulechanged signature oftrezorlib.btc.sign_tx@fielddecorator was replaced by an argument to@expectAddedtrezorlib now has a hardcoded check preventing use of outdated firmware versions#283Ripple support#286Zencash support#287Cardano support#300Ontology support#301Tezos support#302Capricoin support#325limited Monero support (can only get address/watch key, monerowallet is required for signing)support for input flow in tests makes it easier to control complex UI workflows#314protobuf.dict_to_protocan create a protobuf instance from a plain dictsupport for smarter methods in trezord 2.0.25 and upsupport for seedless setuptrezorctl: firmware handling is greatly improved#304,#308trezorctl: Bitcoin-like signing flow is more user-friendlytx_apinow supports Blockbook backend serversChangedbetter reporting for debuglink expected messagesreplaced Ed25519 module with a cleaner, optimized versionfurther reorganization of transports makes them more robust when dependencies are missingcodebase now followsBlackcode stylein Qt modules, Qt5 is imported first#315TxApiInsightis justTxApidevice.resetanddevice.recovernow have reasonable defaults for all argumentsprotobuf classes are no longer part of the source distribution and must be compiled locally#284Stellar: addresses are always stringsRemovedset_tx_apimethod onTrezorClientis replaced by an argument forsign_txcaching functionality ofTxApiwas moved to a separate test-support classStellar: public key methods removedEncryptMessageandDecryptMessageactions are goneFixed:TrezorClientcan now detect when a HID device is removed and a different one is plugged in on the same pathtrezorctl now works with Click 7.0 and considers "_" and "-" as same in command names#314bash completion fixedStellar: several bugs in the XDR parser were fixed0.10.2- 2018-06-21Addedstellar_get_addressand_public_keyfunctions supportshow_displayparametertrezorctl:stellar_get_addressand_public_keycommands for the respective functionalityRemovedtrezorctl:list_coinsis removed because we no longer parse the relevant protobuf field
(and newer Trezor firmwares don't send it)#277Fixedtest support module was not included in the release, so code relying on the deprecatedckd_publicmodule would fail#2800.10.1- 2018-06-11Fixedprevious release fails to build on Windows#2740.10.0- 2018-06-08AddedLisk support#197Stellar support#167,#268Wanchain support#230support for "auto lock delay" featureTrezorClienttakes an additional argumentstatethat allows reusing the previously entered passphrase#241USB transports mention udev rules in exception messages#245log.enable_debug_outputfunction turns on wire logging, instead of having to useTrezorClientVerboseBIP32 paths now support123hin addition to123'to indicate hardeningtrezorctl:-pnow supports prefix search for device path#226trezorctl: smarter handling of firmware updates#242,#269Changedreorganized transports and moved into their owntransportsubmoduleprotobuf messages and coins info is now regenerated at build time from thetrezor-commonrepository#248renameded25519rawto_ed25519to indicate its privatenessrenameded25519cositocosiand expanded its APIprotobuf messages are now logged through Python'sloggingfacility instead of custom printing throughVerboseWireMixinclient.format_protobufis moved toprotobuf.format_messagetools.Hashis renamed totools.btc_hashcoinsmodulecoins_txapiis renamed totx_api.coins_slip44is renamed toslip44.build: stricter flake8 checksbuild: split requirements to separate filestests: unified finding test device, while respectingTREZOR_PATHenv variable.tests: auto-skip appropriately marked tests based on Trezor device versiontests: only show wire output when run with-vtests: allow runningxfailed tests selectively based onpytest.inidocs: updated README with clearer install instructions#185docs: switched changelog to Keep a Changelog format#94Deprecatedckd_publicis only maintained intests.supportsubmodule and considered privateTrezorClient.expand_pathis moved to plain functiontools.parse_pathTrezorDeviceis deprecated in favor oftransport.enumerate_devicesandtransport.get_transportXPUB-related handling intoolsis slated for removalRemovedmost Python 2 compatibility constructs are gone#229TrezorClientVerboseandVerboseWireMixinis removedspecifictx_api.TxApi*classes removed in favor ofcoins.tx_apiclient.PRIME_DERIVATION_FLAGis removed in favor oftools.HARDENED_FLAGandtools.H_()hard dependency on Ethereum libraries and HIDAPI is changed into extras that need to be
specified explicitly. Requiretrezor[hidapi]ortrezor[ethereum]to get them.FixedWebUSB enumeration returning bad devices on Windows 10#223sign_txoperation sending empty address string#237Wrongly formatted Ethereum signatures#236protobuf layer would wrongly encode signed integers#249,#250protobuf pretty-printing broken on Python 3.4#256trezorctl: Matrix recovery on Windows wouldn't allow backspace#207aes_encfs_getpass.py: fixed Python 3 bug#1690.9.1- 2018-03-05Addedproper support for Trezor model Tsupport for Monacoinimprovements totrezorctl:add pretty-printing of features and protobuf debug dumps (fixes#199)supportTREZOR_PATHenvironment variable to preselect a Trezor device.Removedgradually dropping Python 2 compatibility (pypi package will now be marked as Python 3 only)