How to run btcrecover yourself — the complete walkthrough.

Before you start: is btcrecover the right tool?

This guide is the full btcrecover walkthrough. If you’d rather attack with masks and wordlists, read the hashcat walkthrough instead. Both start with the same step: protect your file and collect your clues.

Before investing an evening, check the math first: is recovery technically possible? — that page takes 5 minutes and will save you from burning days on a case that was never viable.

The walkthrough — six steps

1. 1

   Protect what you have — before anything else

   Make a read-only copy of the wallet file and run every command on that copy. Never on the original, never on your only backup. Do it on a machine that is offline or at least clean, and download everything only from official sources. Ten minutes here prevents the two most common ways a case becomes unrecoverable — a corrupted only-copy and a trojan disguised as a “cracker”. The full protection rules, plus the printable offline toolkit that keeps every step on paper.

2. 2

   Find the wallet file

   You need the encrypted file itself. Common paths: %appdata%\Bitcoin\wallet.dat (Bitcoin Core), %appdata%\Electrum\wallets, wallet.aes.json (Blockchain.com), UTC--…json (Ethereum keystores), MultiBit’s key-backup folder. Don’t know where yours lives? The full file-location guide covers Windows, macOS and Linux. btcrecover also ships a walletfinder.py that scans a folder tree and auto-detects supported wallet files.

3. 3

   Install btcrecover (10 minutes)

   There is no installer — you download, unzip and install the Python dependencies. The official steps from the project’s own documentation:

   # 1. Download from the official repository https://github.com/3rdIteration/btcrecover → Code → Download ZIP # 2. Unzip, then open a terminal in the btcrecover-master folder cd Downloads/btcrecover-master # 3. Create and activate a virtual environment (recommended — keeps your system Python untouched) python3 -m venv .venv source .venv/bin/activate # 4. Install the requirements (Python 3.10–3.13 recommended; needs Python installed first) python -m pip install -r requirements.txt # 5. Check it works python btcrecover.py --help

   On Windows use py -m venv .venv then .venv\Scripts\activate, and the commands use python. A pip error about an externally-managed environment is Python protecting your system install — do not bypass it with --break-system-packages as a routine step; the virtual environment above is the fix. Reserve that flag for a last resort in a disposable VM or container.

4. 4

   Build your token list — the step that decides everything

   btcrecover builds whole passwords from the pieces you remember. Those pieces live in a plain-text file, usually called tokens.txt. The full method — what to write down, how to turn memory into candidates — is the password hint list guide, which includes a practice demo, the patterns for partial memory (fragments with unknown middles, endings, or lengths), and a downloadable offline builder that works without internet. The file format, in short:

   # one token per line; passwords are combinations of tokens from each line # space-separated tokens on one line = alternatives (never combined together) # + at line start = this token must be in every guess # ^ = token only at the start · $ = token only at the end # %d %1,3d %a %[chars] %y = wildcards (digit, 1–3 digits, letter, chars, symbol) Amira amira AMIRA 2017 2016 2015 %0,1y

   That file covers “Amira + a year + maybe one symbol at the end” — a few hundred combinations, seconds to test. %y is “any single symbol”, so %0,1y means “zero or one symbol”. Add --max-tokens 4 if you’re not sure how many pieces combine. Before running a long search, always test the list — it lists the candidates without touching the wallet:

   python btcrecover.py --listpass --tokenlist tokens.txt

   Already have full candidate passwords? (from old notes, exports, or another tool) — use --passwordlist instead of a token list: each line is tried verbatim as one complete password. Without a filename, btcrecover prompts you to type them one per line; with a file, --passwordlist candidates.txt reads them directly. Typo options still apply on top.

5. 5

   Run the recovery

   Point btcrecover at your copied wallet file and token list. The classic wallet.dat case:

   python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --autosave progress.sav

   Two options that routinely save the case:

   • Typos — if the password is probably right but mistyped: --typos 1 --typos-case --typos-swap --typos-repeat tries nearby variants (caps-lock slip, swapped or doubled characters). Keep the typo budget small — it multiplies the work.
   • Autosave — --autosave progress.sav writes progress every ~5 minutes; if the machine reboots or you close the window, resume with --restore progress.sav (that flag must be the only option on the command line) instead of starting over.

   You’ll see a progress bar with an ETA. If the ETA says two weeks, that is the real answer about your current token list — see step 6.

   Three commands that save time. --length-min 8 --length-max 14 limits the guesses to the length you remember — a huge cut. --no-dupchecks skips duplicate-guess checking to save memory on very large token lists (add it up to four times). And if an ETA above one week makes btcrecover refuse to start, --max-eta 336 raises the built-in one-week cap for cases you want to let run.

   Two more for tricky memory. --regex-only '^[A-Z].*[0-9][0-9]$' tries only candidates that match the pattern (here: capital first, two digits at the end), and --regex-never does the opposite. --password-repeats-pretypos also tests doubled passwords (passwordpassword) — a common habit worth covering.

6. 6

   Read the result — and know when to stop

   Found: Password found: 'Amira2017@' — btcrecover stops, prints the password, and you unlock the wallet with it. Exhausted: Password search exhausted — every combination was tried and none worked. That means your memory of the pieces was wrong somewhere. Widen the tokens (more years, more spellings, other patterns you used) and try again. If the math says the search needs weeks of GPU time, let the feasibility numbers decide before you invest more — a fresh clue beats more GPU time, and the wallet files stay safe meanwhile.

Going further — three cases worth knowing

• The BIP39 passphrase (25th word). Know your seed but lost the extra passphrase? btcrecover tests candidates against your wallet without a file: python btcrecover.py --bip39 --mnemonic "your twelve or twenty four words here" --addrs <known-address> --addr-limit 10 --tokenlist tokens.txt — you need the mnemonic plus one known address or your xpub as the target, and Ethereum/altcoin cases often need the appropriate --wallet-type. The 25th word, explained.
• Altcoins. Litecoin, Dogecoin, BCH and dozens of Bitcoin-derived coins share the wallet.dat format — btcrecover handles them with --wallet-type or --bip32-path. Fork wallets, explained.
• MultiBit Classic. If you kept the key-backup files, testing against a .key file is roughly 1,000× faster than the full wallet. The MultiBit guide.

Password found — now what?

A btcrecover success means the password is verified and the wallet opens — not that the journey is over. Do these in order:

1. 1
   Verify before you move anything. Open the wallet with the recovered password and confirm it loads with the expected addresses and balance before moving funds. (A wrong variant opening a different, empty wallet is a seed-passphrase phenomenon, not a verified encrypted-wallet password — see the passphrase guide.)
2. 2
   Store the password safely. The moment it works, save it in a password manager and keep one written fallback — then never reuse it for another wallet. That is the whole storage rule.
3. 3
   Note the balance first. Write down the balance and addresses before transferring, so you can spot problems immediately.
4. 4
   Move the funds to a fresh wallet. Old wallet software is discontinued and often unsafe to keep using — and importing old keys into modern software does not make them fresh. Create a new wallet with a new seed, back it up and verify it, then send/sweep the funds to its addresses.
5. 5
   Use only official software. The moment you have access is also the moment you are most careless — download wallets only from official sites, never from search ads or links in messages.

Now that the password is back, make sure it stays that way — never losing access covers the storage rule.

Frequently asked questions

Sources & references

1. btcrecover documentation
2. 3rdIteration/btcrecover — maintained fork (source code)