If the Bitcoin Core Wallet Migration Tool is supposed to be creating descriptors for sparse keys (as it's supposed to support pre deterministic wallets), then why doesn't Bitcoin Core allow using importprivkey on a descriptor wallet?

I'm trying to, and it's telling error code -4 (type of wallet does not support this command).

How can I import a private key to a descriptor wallet?

  • Hey Mercedes, I edited your question to add the question that I perceived to be implicitly asked here. Please feel free to rollback or further amend the changes I made.
    – Murch
    May 23 at 16:57

2 Answers 2


The migration tool has not been implemented yet, and it is not for manually importing keys. Rather it takes an existing wallet and migrates everything in that wallet.

As the error message says, descriptor wallets do not support the importprivkey. You will have to use importdescriptors with the private key you want to import as part of the proper descriptor.

For example, if you wanted to import the p2wpkh address for a private key, you would make a descriptor of the form wpkh(<privkey>). Then use getdescriptorinfo to get the checksum and create wpkh(<privkey>)#<checksum>, and then use importdescriptors to import that descriptor.


To give a bit more context to Andrew Chow's answer: the reason why this isn't any easier is that the concept of "importing a private key" is an insufficient method for describing what a wallet should do, and the wrong way to think about wallets in the first place. While it is possible to convert wallets with keys imported to them to approximately equivalent descriptor wallets, this does not mean that it's the best way when importing things. Descriptors and descriptor wallets allow you to be precise about what you want to import, and the importdescriptors RPC lets you do that.

In more detail, this is roughly the philosophy behind the two types of wallets supported by Bitcoin Core:

  • legacy wallets A legacy wallet is a collection of private keys, and loosely structured additional information such as scripts and addresses. Any output which can be spent or observed with those keys/scripts/addresses is considered to "belong" to the wallet. If you import a new key to a wallet, this immediately results in treating payments to the P2PK, P2PKH, P2WPKH, P2SH-P2WPKH, and possibly more, addresses derived from that key to be watched. This is inefficient, hard to describe and reason about, and just doesn't scale well with new wallet constructions being added (e.g. P2TR), and even harder to deal with when multisig across deviced or participants is added.
  • Descriptor wallets In a descriptor wallet, the outputs considered part of the wallet can be described exactly using a simple "language" which contains all metadata about how the keys are used. If you want just P2PKH addresses derived from a key, you can say that. If you want P2SH-wrapped P2WSH multisig across multiple devices you can say that too, and it will work exactly the same.

In short: the old model of how we thought of wallets wasn't manageable anymore, and "importing a key" only made sense in that kind of thinking. In the new model, you don't import keys, you import a description of exactly what you want the wallet to do.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.