Skip to main content
btcrecover.py is designed for situations where you remember most of your password but need to try variations — different capitalizations, a forgotten character, slightly different spellings. You describe what you remember and BTCRecover searches all combinations.
1

Locate your wallet file

Find and copy your wallet file to the BTCRecover directory. Common locations:
WalletWindows path
Bitcoin Core%appdata%\Bitcoin\wallet.dat
Electrum%appdata%\Electrum\wallets\
MultiBit HD%appdata%\MultiBitHD\ (file: mbhd.wallet.aes)
MultiBit Classic%appdata%\MultiBit\multibit-data\key-backup\ (use .key files)
Bither%appdata%\Bither\address.db
Blockchain.comwallet.aes.json (download via developer tools)
Metamask%localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\nkbihfbeogaeaoehlefnkodbefgpgknn
mSIGNA%homedrive%%homepath%\*.vault
Always work with a copy of your wallet file. BTCRecover is beta software and should never be run against your only copy.
For BIP-39 passphrases (the “25th word”), you do not need a wallet file — use the --bip39 flag instead (see examples below).
2

Create a password list or token list

BTCRecover needs either a password list (one candidate per line) or a token list (fragments that get combined).For a simple password list, create a file called passwordlist.txt with one candidate password per line:
MyPassword1
mypassword1
MyPassword!
mypassword!
MyP@ssword1
For a token list, create a file called tokens.txt where each line is a fragment. BTCRecover combines them into candidates:
# Tokens are combined in all orders
Cairo
Beetlejuice Betelgeuse
Hotel_california
The token list format supports anchors, mutual exclusion, wildcards (%d for digit, %a for letter, %H for hex character), and inline command-line options. See token lists for the full syntax.
3

Run btcrecover.py

Open a terminal in the BTCRecover directory and run the recovery command.
python btcrecover.py --wallet wallet.dat --passwordlist passwordlist.txt
BTCRecover displays a progress bar and ETA. If the password is found it prints:
Password found: 'Passwd42'
If all candidates are exhausted without a match:
Password search exhausted

​
Example commands

The commands below use test wallets and addresses that ship with BTCRecover. They find a result immediately and are safe to run as-is.

​
BIP-38 encrypted paper wallets

BIP-38 wallets use scrypt, so brute-force is slow. These work with keys from bitaddress.org, liteaddress.org, paper.dash.org, and others. 
# Bitcoin (default — no currency flag needed)
python btcrecover.py --bip38-enc-privkey 6PnM7h9sBC9EMZxLVsKzpafvBN8zjKp8MZj6h9mfvYEQRMkKBTPTyWZHHx --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

# Litecoin
python btcrecover.py --bip38-enc-privkey 6PfVHSTbgRNDaSwddBNgx2vMhMuNdiwRWjFgMGcJPb6J2pCG32SuL3vo6q --bip38-currency litecoin --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

# Dash
python btcrecover.py --bip38-enc-privkey 6PnZC9Snn1DHyvfEq9UKUmZwonqpfaWav6vRiSVNXXLUEDAuikZTxBUTEA --bip38-currency dash --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

​
BIP-39 passphrases (hardware and software wallets)

Use --bip39 instead of --wallet when recovering a BIP-39 passphrase (the “25th word”). Supported hardware wallets include Trezor, Ledger, Keepkey, Coldcard, and Bitbox02. 
# Bitcoin — supports Legacy, Segwit, and Native Segwit addresses automatically
python btcrecover.py --bip39 --addrs 1AmugMgC6pBbJGYuYmuRrEpQVB9BBMvCCn --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "certain come keen collect slab gauge photo inside mechanic deny leader drop"

# Ethereum
python btcrecover.py --wallet-type ethereum --addrs 0x4daE22510CE2fE1BC81B97b31350Faf07c0A80D2 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

# Bitcoin Cash
python btcrecover.py --wallet-type bch --addrs bitcoincash:qqv8669jcauslc88ty5v0p7xj6p6gpmlgv04ejjq97 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

# Litecoin
python btcrecover.py --wallet-type litecoin --addrs LdxLVMdt49CXcrnQRVJFRs8Yftu9dE8xxP --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

# Cardano (Shelley)
python btcrecover.py --wallet-type cardano --addrs addr1q90kk6lsmk3fdy54mqfr50hy025ymnmn5hhj8ztthcv3qlzh5aynphrad3d26hzxg7xzzf8hnmdpxwtwums4nmryj3jqk8kvak --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "ocean hidden kidney famous rich season gloom husband spring convince attitude boy"

# Dogecoin
python btcrecover.py --wallet-type dogecoin --addrs DSTy3eptg18QWm6pCJGG4BvodSkj3KWvHx --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

# Tron
python btcrecover.py --wallet-type tron --addrs TGvJrj5D8qdzhcppg9RoLdfbEjDYCne8xc --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "have hint welcome skate cinnamon rabbit cable payment gift uncover column duck scissors wedding decorate under marine hurry scrub rapid change roast print arch"

# Polkadot (with substrate derivation path)
python btcrecover.py --wallet-type polkadotsubstrate --addrs 12uMBgecqfkHTYZE4GFRx847CwR7sfs2bTdPbPLpzeMDGFwC --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "toilet assume drama keen dust warrior stick quote palace imitate music disease" --substrate-path "//hard/soft"

​
Electrum wallets (non-BIP39)

Electrum uses its own seed format. Use --wallet-type electrum2 for Electrum and its altcoin forks. 
python btcrecover.py --wallet-type electrum2 --addrs bc1q6n3u9aar3vgydfr6q23fzcfadh4zlp2ns2ljp6 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "quote voice evidence aspect warfare hire system black rate wing ask rug"

​
Ethereum Keystore files

python btcrecover.py --wallet ./btcrecover/test/test-wallets/utc-keystore-v3-scrypt-myetherwallet.json --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

​
Metamask and browser extension wallets

# Metamask (Chrome) — use the full extension data folder as the wallet path
python btcrecover.py --wallet "%localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\nkbihfbeogaeaoehlefnkodbefgpgknn" --passwordlist passwordlist.txt

​
SLIP-39 passphrases

Provide two or more SLIP-39 shares (a quorum is required): 
# Bitcoin
python btcrecover.py --slip39 --addrs bc1q76szkxz4cta5p5s66muskvads0nhwe5m5w07pq --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --slip39-shares "hearing echo academic acid deny bracelet playoff exact fancy various evidence standard adjust muscle parcel sled crucial amazing mansion losing" "hearing echo academic agency deliver join grant laden index depart deadline starting duration loud crystal bulge gasoline injury tofu together"

# Ethereum
python btcrecover.py --slip39 --wallet-type ethereum --addrs 0x0Ef61684B1E671dcBee4D51646cA6247487Ef91a --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --slip39-shares "hearing echo academic acid deny bracelet playoff exact fancy various evidence standard adjust muscle parcel sled crucial amazing mansion losing" "hearing echo academic agency deliver join grant laden index depart deadline starting duration loud crystal bulge gasoline injury tofu together"

​
Brainwallets

# SHA-256 brainwallet — Bitcoin (checks both compressed and uncompressed)
python btcrecover.py --brainwallet --addrs 1BBRWFHjFhEQc1iS6WTQCtPu2GtZvrRcwy --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

# Warpwallet — Bitcoin with salt
python btcrecover.py --warpwallet --warpwallet-salt btcr-test-password --addrs 1FThrDFjhSf8s1Aw2ed5U2sTrMz7HicZun --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

# Warpwallet — Litecoin with salt
python btcrecover.py --warpwallet --warpwallet-salt btcr-test-password --crypto litecoin --addrs LeBzGzZFxRUzzRAtm8EB2Dw74jRfQqUZeq --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

​
Useful options

OptionDescription
--typos NApply up to N typos per candidate
--typos-capslockTry the whole password with caps lock on
--typos-swapSwap two adjacent characters
--typos-caseChange the case of one character
--typos-deleteDelete one character
--typos-repeatRepeat (double) one character
--autosave FILESave progress every ~5 minutes to resume later
--restore FILEResume from an autosave file
--listpassPrint all candidate passwords instead of testing (useful for debugging)
--utf8Enable Unicode support for non-ASCII passwords
To preview what passwords will be tested without running a full search, use --listpass in place of --wallet:
python3 btcrecover.py --listpass --tokenlist tokens.txt | more
For the full token list syntax including wildcards, anchors, and mutual exclusion, see token lists.

Build docs developers (and LLMs) love

Get started for freeTalk to us