btcrecover — The Complete Tutorial

btcrecover is the open-source Python toolkit maintained at github.com/3rdIteration/btcrecover. It is the single most battle-tested password and seed recovery tool in the crypto world, actively maintained since 2014 and used by thousands of wallet owners to recover access to wallets they had written off. This tutorial takes you from git clone to a fully-tuned GPU recovery run.

1. Installing btcrecover

Prerequisites

• Python 3.10 or newer (3.11 recommended).
• pip, venv, and git.
• For GPU acceleration: OpenCL runtime from your GPU vendor (NVIDIA CUDA toolkit ships OpenCL; AMD ROCm; Intel oneAPI).
• 8+ GB RAM for realistic tokenlist sizes.

Install on Linux / macOS

# Ubuntu/Debian prerequisites
sudo apt install python3.11 python3.11-venv python3-pip git build-essential

# Clone
git clone https://github.com/3rdIteration/btcrecover.git
cd btcrecover

# Virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install core dependencies
pip install -r requirements.txt

# Optional: GPU acceleration (pyopencl requires a working OpenCL SDK)
pip install pyopencl

# Verify
python3 btcrecover.py --help | head -20

Install on Windows

# PowerShell
# 1. Install Python 3.11 from python.org (check "Add to PATH")
# 2. Install Git for Windows

git clone https://github.com/3rdIteration/btcrecover.git
cd btcrecover

python -m venv .venv
.venv\Scripts\activate

pip install -r requirements.txt
pip install pyopencl           # optional, GPU

python btcrecover.py --help

2. The two entry points: btcrecover.py and seedrecover.py

3. Tokenlist syntax — the heart of btcrecover

A tokenlist is a plain text file. Each line is a group of alternative tokens; each token is a chunk of password. btcrecover combines one token from each line in every possible order. Understanding this syntax unlocks 90% of btcrecover's power.

Basic: one line = one required token

# tokens.txt
satoshi
2014
!

This will test satoshi2014!, satoshi!2014, 2014satoshi!, 2014!satoshi, !satoshi2014, !2014satoshi, and all shorter subsets (3! = 6 orderings × 2^3 subsets = 48 tests including empty/1/2-token). Tiny keyspace, high hit rate for passwords like "2014satoshi!".

Alternatives on the same line

# Pick one alternative per line
satoshi Satoshi SATOSHI sat0sh1
2014 2015 2016 2017 2018
! ? . $ *

Now 4 × 5 × 5 = 100 combinations per ordering × 6 orderings × subsets = ~600 candidates. Still tiny, but covers capitalisation and leet.

Anchors — positional tokens

# ^ before a token pins it to the start, $ after pins to the end
^password
123
$!
# Always tries: password...!  with 123 somewhere in between

Specific position can be forced with ^N (position N, 1-indexed): ^2password means "password must be at position 2 of the combined result".

Wildcards inside tokens

4. Typo tolerance — the killer feature

Everyone makes typos. btcrecover simulates common ones with --typos N --typos-TYPE flags. N is the maximum number of simultaneous typos to inject per candidate.

# Up to 2 typos, all common kinds
python3 btcrecover.py \
    --wallet wallet.dat \
    --tokenlist tokens.txt \
    --typos 2 \
    --typos-capslock \
    --typos-case \
    --typos-replace "@3\
quot; \
    --typos-insert %d \
    --typos-delete \
    --typos-swap

# Typo types:
#   --typos-capslock   entire password uppercase or lowercase
#   --typos-case       single character case-flip
#   --typos-replace X  swap any char for X
#   --typos-insert X   insert X at any position
#   --typos-delete     drop any single character
#   --typos-swap       transpose two adjacent chars
#   --typos-repeat     repeat a character

Typo count has combinatorial cost. --typos 3 with a 10-character password and 5 typo types generates about C(10,3) × 5^3 = 15,000 expansions per base candidate. Keep tokenlist small when typos are wide.

5. GPU acceleration with OpenCL

For wallet types with GPU kernels (Bitcoin Core wallet.dat, Litecoin-Qt, Ethereum pre-sale, Armory, Blockchain.info v1/v2), btcrecover can reach tens of thousands of guesses per second.

# List available OpenCL devices
python3 btcrecover.py --enable-gpu --list-gpus

# Run with GPU 0, auto-tuned workgroup sizes
python3 btcrecover.py \
    --wallet wallet.dat \
    --tokenlist tokens.txt \
    --enable-gpu \
    --global-ws 4096 \
    --local-ws 256

# Benchmark specific settings
python3 btcrecover.py \
    --wallet wallet.dat \
    --performance \
    --enable-gpu

Tune --global-ws and --local-ws in powers of 2 (typical: 1024, 2048, 4096, 8192). Too large and you hit VRAM limits; too small and the GPU idles. Use the --performance benchmark mode to find the sweet spot before committing to a long run.

6. Real worked examples

Bitcoin Core wallet.dat

python3 btcrecover.py \
    --wallet wallet.dat \
    --tokenlist tokens.txt \
    --typos 2 --typos-case --typos-capslock \
    --enable-gpu \
    --autosave resume.save

Electrum 2.x with seed-backed acceleration

python3 btcrecover.py \
    --wallet default_wallet \
    --passwordlist candidates.txt \
    --dsw                       # decrypt-skip-wallet: xpub-only check

BIP39 seed with 2 missing words

python3 seedrecover.py \
    --wallet-type bip39 \
    --mnemonic "abandon ? ability able about above absent absorb abstract absurd abuse ?" \
    --addrs bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh \
    --addr-limit 5

MetaMask vault

python3 btcrecover.py \
    --wallet vault.json \
    --wallet-type metamask \
    --tokenlist tokens.txt \
    --typos 1

7. Checkpoint and resume

Long recovery runs (days or weeks) need fault tolerance. The --autosave flag writes progress to disk every 5 minutes by default (tunable with --autosave-interval).

# Start with autosave
python3 btcrecover.py --wallet wallet.dat --tokenlist tokens.txt \
    --autosave resume.save

# Power cut happens, reboot, resume exactly where stopped
python3 btcrecover.py --restore resume.save

The save file records the current position in the keyspace, all options used, and a hash of the tokenlist so you cannot accidentally resume with a different input.

8. Tips from hundreds of real recoveries

When btcrecover hits its limit — switch to a GPU farm

Single-GPU btcrecover gets you maybe 100–200 billion guesses per week against Bitcoin Core wallet.dat. For harder cases — longer passwords, more typos, or MetaMask vaults with deep searches — a multi-GPU farm running hashcat in parallel moves 1–5× faster and runs 24/7 on industrial cooling. This is what our service provides when local btcrecover runs exhaust their keyspace without finding the password.

Related guides

• Bitcoin Core wallet.dat recovery — the prime target for btcrecover + GPU.
• Electrum wallet password recovery — includes seed-backed attack details.
• MetaMask vault recovery — extract vault, then btcrecover.
• BIP39 seed recovery — seedrecover.py deep dive.
• Crypto recovery scams guide — why "online btcrecover" is always a scam.

Frequently asked questions