FAQ and Troubleshooting

BTCRecover is hanging at 'Counting passwords...' — what do I do?

When BTCRecover starts, it counts all password candidates and records duplicates so that no password is tested twice. For large search spaces this can consume a very large amount of memory and appear to hang.Run with --no-dupchecks to skip the most memory-intensive duplicate-checking pass:

python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --no-dupchecks

You can specify --no-dupchecks up to four times for progressively less duplicate checking:

Times specified	Effect
1×	Disables the most comprehensive (and most memory-intensive) check
2×	Disables a secondary check that rarely saves much memory
3×	Disables a check that consumes very little memory; rarely useful
4×	Disables all remaining checks; only for debugging

If you also use --no-eta, add --no-dupchecks at the same time — skipping the ETA calculation also skips the counting phase, so duplicate checking provides no benefit without it.

For MultiBit Classic and Electrum wallets, a single --no-dupchecks is often beneficial even when memory is not a concern, because duplicate checking can reduce CPU efficiency with those wallet formats.

How do I speed up the search?

Several strategies can improve search performance:Use GPU acceleration for supported wallet types (Bitcoin Core, Blockchain.com, Electrum passwords, BIP39 and Electrum seeds):

python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --enable-opencl

List available OpenCL devices first:

python btcrecover.py --opencl-info

Tune the thread count. BTCRecover uses all logical CPU cores by default. For MultiBit and Electrum wallets, reducing threads slightly with --threads can sometimes improve throughput:

python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --threads 4

Split the search across multiple machines with --worker:

# Machine 1 of 3
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --worker 1/3

# Machine 2 of 3
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --worker 2/3

Add --no-dupchecks for MultiBit and Electrum wallets to improve CPU efficiency.Narrow the search space. The more specific your tokenlist or passwordlist, the faster the search. Use --typos only as high as necessary, and enable only the typo types relevant to your situation.

Seed recovery found a result but the wallet is empty — what happened?

The most common cause is a wrong or missing BIP39 passphrase. Every BIP39 passphrase is valid — even an empty string is a valid passphrase — so BTCRecover will declare success as soon as it finds a seed+passphrase combination that derives the target address, without knowing whether the account actually holds funds.If your seed was correct but the wallet is empty, you likely have one of these situations:

You used a BIP39 passphrase. The seed alone produces an empty wallet; the correct passphrase is required to reach your funds. Use btcrecover.py --bip39 with --mnemonic and a passwordlist to search for the passphrase.
The address you supplied belongs to a different derivation path. Try a different --bip32-path or use --pathlist to search multiple paths simultaneously.
The address belongs to a different coin or address type. Confirm that the --wallet-type and address format (Legacy, SegWit, Native SegWit) match the wallet you originally used.

A successful seed recovery result only guarantees that the seed derives the address you supplied. Always verify by checking your address on a block explorer before concluding that funds are accessible.

What is the difference between btcrecover.py and seedrecover.py?

	`btcrecover.py`	`seedrecover.py`
Primary purpose	Recover a wallet password or passphrase	Recover a seed phrase (mnemonic)
Input	Wallet file, data extract, BIP39 mnemonic, BIP38 key, or raw private key	Your best guess of the mnemonic
Searches for	The password or BIP39 passphrase that unlocks a known seed	The correct mnemonic by trying substitutions for missing or wrong words
GUI	No	Yes (launch with no arguments)
When to use	You know your seed but forgot the password or passphrase	You have your seed backup but some words are missing, wrong, or reordered

For BIP39 passphrase recovery (the “25th word”), use btcrecover.py --bip39.For recovering the seed itself (the 12–24 word mnemonic), use seedrecover.py.

My coin isn't listed — can BTCRecover still help?

Possibly. BTCRecover supports many “Bitcoin-like” cryptocurrencies that share the same derivation standard (BIP32/44/49/84) even if they are not explicitly named. Try using --wallet-type bip39 and supplying a known address from the coin; if the address format is standard (Legacy P2PKH, P2SH, or Native SegWit), BTCRecover may derive a match.For coins with unusual address formats or non-standard derivation paths, use --bip32-path to specify the coin’s derivation path manually, or --pathlist to search multiple paths at once.Coins with their own derivation modules — such as Cardano, Polkadot, Solana, Stellar, Tron, and others — require the matching --wallet-type value. See the supported coins table for the full list.

What is the difference between a BIP39 passphrase and a seed phrase?

	Seed phrase (mnemonic)	BIP39 passphrase
Also called	Recovery phrase, backup words, mnemonic	”25th word”, extra word, plausible deniability passphrase
Word count	12, 15, 18, 21, or 24 words	Any string (including empty)
Purpose	The root secret from which all wallet keys are derived	An optional extra layer applied on top of the seed
Error behavior	Invalid seeds produce an error or checksum failure	Every passphrase is valid; a wrong one produces an empty wallet
Recovery tool	`seedrecover.py`	`btcrecover.py --bip39`

If you are seeing an empty wallet with no transaction history after restoring your seed, you almost certainly have a BIP39 passphrase that you need to recover. Use btcrecover.py --bip39 with your seed, a known address, and a passwordlist.

What is an Address Database and when do I need one?

An Address Database is a file that contains a large set of addresses derived from the blockchain. You need one when you want to search for a seed or passphrase but do not have a specific known address to verify against.Situations where an AddressDB is useful:

You do not remember which address(es) belong to the wallet you are recovering.
You want to check whether any address in the wallet matches without specifying one in advance.
You are recovering a raw private key and do not have the corresponding address.

There is no significant search-speed penalty for using an AddressDB. The tradeoff is the time and disk space required to build it from blockchain data.Supply the database with --addressdb:

python btcrecover.py --bip39 \
  --addressdb ./addresses.db \
  --passwordlist ./passwords.txt \
  --mnemonic "your seed words here"

Does BTCRecover support GPU acceleration?

Yes, via OpenCL. GPU acceleration is supported for:

Bitcoin Core wallet passwords
Blockchain.com main and second passwords
Electrum wallet passwords
BIP39 seed recovery
Electrum seed recovery

GPU acceleration is available for BIP39 seed recovery but not for BIP39 passphrase recovery (the “25th word”).

To enable OpenCL acceleration, add --enable-opencl to your command. To list available devices first:

python btcrecover.py --opencl-info

For Bitcoin Core wallets specifically, the legacy --enable-gpu flag (with --global-ws and --local-ws) is also available.BIP38 (encrypted paper wallets) also support GPU acceleration, but the scrypt key derivation function provides only a modest speed improvement over CPU even with a powerful GPU.

How do I resume an interrupted recovery?

Use --autosave to save progress every five minutes to a file. If the file already exists when BTCRecover starts, it will automatically restore from it and continue where it left off.

# Start (or resume) with autosave
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --autosave ./recovery.sav

To restore explicitly from a saved file (must be the only argument):

python btcrecover.py --restore ./recovery.sav

If you did not use --autosave, you can resume manually using --skip COUNT to skip the number of passwords already tried. The progress bar shows how many passwords have been tested.

The --autosave file stores your tokenlist path and all search options. Keep it in a secure location, as it may contain sensitive information about the passwords being tried.

Is it safe to run BTCRecover on a computer I don't fully trust?

BTCRecover includes “extract scripts” that let you pull just enough information from your wallet file to perform password recovery, without exposing your private keys or addresses to the machine running the recovery. This is useful when renting cloud compute or asking someone else to run the search.The extract script generates a short data string. You then run:

python btcrecover.py --data-extract --passwordlist ./passwordlist.txt

and paste the extracted string when prompted.Even with an extract, BTCRecover itself still reads your tokenlist or passwordlist from disk and does not overwrite sensitive password candidates in memory. If high security is required, run the tool inside a VM on a hard disk drive (not an SSD) and securely delete the VM when finished.

Why does BTCRecover run a benchmark before starting the search?

Before the main search begins, BTCRecover runs a short benchmark to estimate how quickly passwords or seeds can be checked. This lets it calculate an accurate ETA.By default the benchmark runs for up to 30 seconds. You can shorten it with:

--pre-start-seconds 5

Or skip it entirely with:

--skip-pre-start

Skipping the benchmark may reduce the accuracy of the ETA, but does not affect the recovery itself. If you are running many short searches and do not need an ETA, use --no-eta to skip both the benchmark and the counting phase entirely.

Supported Wallets

Command Reference

Examples & Troubleshooting

FAQ and Troubleshooting

Build docs developers (and LLMs) love