btcrecover.py Options

Wallet input

Flag	Argument	Description
`--wallet`	`FILE`	The wallet file to recover. Required unless `--data-extract`, `--bip39`, `--slip39`, `--brainwallet`, `--rawprivatekey`, or `--bip38-enc-privkey` is used.
`--data-extract`	—	Prompt for data extracted by one of the `extract-*` scripts instead of using a wallet file. Allows secure recovery on untrusted hardware.
`--data-extract-string`	`STRING`	Pass the extracted data directly as a command-line argument instead of being prompted.
`--android-pin`	—	Search for the spending PIN instead of the backup password in a Bitcoin Wallet for Android/BlackBerry.
`--blockchain-secondpass`	—	Search for the second password in a Blockchain.com wallet instead of the main password.
`--blockchain-correct-mainpass`	`STRING`	Supply (or be prompted for) the main password when recovering the second password from a Blockchain.com wallet.
`--msigna-keychain`	`NAME`	Keychain whose password to search for in an mSIGNA vault.

Example — wallet file

python btcrecover.py --wallet ./wallet.dat --passwordlist ./passwordlist.txt

Example — data extract (offline/untrusted hardware)

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

Password sources

Exactly one of --tokenlist or --passwordlist must be supplied (unless using --correct-wallet-password).

Flag	Argument	Description
`--tokenlist`	`FILE`	File of tokens / partial passwords. BTCRecover assembles full candidates by combining tokens. Supports wildcards and positional anchors.
`--passwordlist`	`FILE` or `-`	File of complete passwords, one per line. Use `-` to read from stdin.
`--has-wildcards`	—	Parse and expand wildcards inside a `--passwordlist` (wildcards are only expanded in tokenlists by default).
`--passwordlist-arguments`	—	Allow the first line of the passwordlist file to start with `#--` and supply additional CLI options.
`--exclude-passwordlist`	`FILE` or `-`	Never try passwords read from this file.
`--max-tokens`	`COUNT`	Maximum number of tokens combined per guess.
`--min-tokens`	`COUNT`	Minimum number of tokens combined per guess (default: 1).
`--keep-tokens-order`	—	Do not permute token order; combine tokens in the order they appear in the file.
`--seedgenerator`	—	Use tokenlist as a seed word list (for BIP39 seed descrambling).
`--mnemonic-length`	`COUNT`	Expected word count of the seed (for seedgenerator mode).
`--correct-wallet-password`	`STRING`	Supply the known correct password directly (skips the search; useful for dumping wallet keys).
`--correct-wallet-secondpassword`	`STRING`	Supply the correct second password directly.
`--wildcard-custom-list-e`	`FILE`	Custom word list for the `%e` wildcard.
`--wildcard-custom-list-f`	`FILE`	Custom word list for the `%f` wildcard.
`--wildcard-custom-list-j`	`FILE`	Custom word list for the `%j` wildcard.
`--wildcard-custom-list-k`	`FILE`	Custom word list for the `%k` wildcard.
`--listpass`	—	Print all password combinations that would be tried, then exit (does not attempt recovery).

Example — tokenlist

python btcrecover.py --wallet wallet.dat --tokenlist ./tokens.txt

Example — passwordlist from stdin

cat passwords.txt | python btcrecover.py --wallet wallet.dat --passwordlist -

Typo simulation

Typo flags tell BTCRecover to also test near-misses of each password candidate. You must specify --typos COUNT to enable typo simulation, then choose one or more typo types.

Flag	Argument	Description
`--typos`	`COUNT`	Simulate up to this many typos per guess. Required to activate any typo type.
`--min-typos`	`COUNT`	Enforce a minimum number of typos per guess.
`--typos-capslock`	—	Try the password with Caps Lock turned on.
`--typos-swap`	—	Swap two adjacent characters.
`--typos-repeat`	—	Add a repeated character.
`--typos-delete`	—	Delete a character.
`--typos-case`	—	Change the case of a character.
`--typos-closecase`	—	Change the case of a character that is adjacent to another changed-case character.
`--typos-replace`	`WILDCARD`	Replace a character with one from a wildcard set.
`--typos-insert`	`WILDCARD-STRING`	Insert a string or wildcard at a position.
`--typos-extra-word`	—	Add one extra word (for BIP39 passphrase).
`--max-typos-<type>`	`COUNT`	Limit the number of a specific typo type per guess (e.g., `--max-typos-delete 1`).
`--max-adjacent-inserts`	`COUNT`	Maximum number of `--typos-insert` strings that can be inserted between a single pair of characters (default: 1).
`--custom-wild`	`STRING`	Custom character set for the `%c` wildcard.
`--regex-only`	`REGEX`	Only try passwords matching this regular expression.
`--regex-never`	`REGEX`	Never try passwords matching this regular expression.
`--length-min`	`COUNT`	Skip passwords shorter than this length.
`--length-max`	`COUNT`	Skip passwords longer than this length.
`--truncate-length`	`COUNT`	Truncate passwords to this length before testing (useful for Trezor passphrase limits, etc.).
`--delimiter`	`STRING`	Delimiter between tokens in the tokenlist or columns in a typos-map (default: whitespace).
`--password-repeats-pretypos`	—	Also test multiple repetitions of each candidate password before applying typos (e.g., `passwordpassword`).
`--password-repeats-posttypos`	—	Also test multiple repetitions after applying typos.
`--max-password-repeats`	`COUNT`	Maximum number of additional repetitions to produce (default: 2).

Example — single character deletion or swap

python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt \
  --typos 2 --typos-delete --typos-swap

BIP39 / SLIP39 passphrase recovery

Use these flags when recovering a BIP39 “25th word” passphrase or a SLIP39 passphrase, rather than a wallet file password.

Flag	Argument	Description
`--bip39`	—	Search for a BIP39 passphrase (no wallet file required).
`--slip39`	—	Search for a SLIP39 passphrase.
`--slip39-shares`	`MNEMONIC [MNEMONIC ...]`	One or more SLIP39 share mnemonics.
`--mnemonic`	`MNEMONIC`	Your best guess of the mnemonic. Prompted interactively if omitted.
`--mnemonic-prompt`	—	Prompt for the mnemonic via the terminal instead of the GUI.
`--skip-mnemonic-checksum`	—	Skip BIP39 mnemonic checksum validation.
`--wallet-type`	`TYPE`	Coin/wallet type (e.g., `ethereum`, `litecoin`, `cardano`). Default: `bitcoin`.
`--addrs`	`ADDRESS [...]`	One or more known addresses in the wallet to verify against.
`--addr-limit`	`COUNT`	Number of addresses to generate and check per derivation path.
`--mpk`	`XPUB`	Master public key (xpub/ypub/zpub) instead of individual addresses.
`--addressdb`	`FILE`	Path to an address database file (alternative to `--addrs`).
`--bip32-path`	`PATH [PATH ...]`	One or more BIP32 derivation paths. Default: BIP44, BIP49, and BIP84 account 0.
`--substrate-path`	`PATH [PATH ...]`	Substrate derivation path(s) for Polkadot (e.g., `//hard/soft`).
`--language`	`LANG-CODE`	BIP39 wordlist language (default: auto-detected).
`--force-p2sh`	—	Force checking P2SH SegWit addresses on all derivation paths.
`--force-p2tr`	—	Force checking Taproot (P2TR) addresses on all derivation paths.
`--force-bip44`	—	Force checking BIP44 legacy addresses regardless of supplied address type.
`--force-bip84`	—	Force checking BIP84 native SegWit addresses regardless of supplied address type.
`--disable-p2sh`	—	Disable P2SH SegWit address checking.
`--disable-p2tr`	—	Disable Taproot address checking.
`--disable-bip44`	—	Disable BIP44 legacy address checking.
`--disable-bip84`	—	Disable BIP84 native SegWit checking.
`--checksinglexpubaddress`	—	Check non-standard single-address wallets (e.g., Atomic Wallet, MyBitcoinWallet).

Example — Bitcoin BIP39 passphrase

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"

Brainwallet and BIP38

Flag	Argument	Description
`--brainwallet`	—	Search for a SHA256(passphrase) brainwallet key.
`--rawprivatekey`	—	Search for a raw private key with missing/damaged characters.
`--warpwallet`	—	Treat the brainwallet as a Warpwallet or Memwallet (scrypt-based).
`--warpwallet-salt`	`STRING`	Salt for Warpwallet (typically your email address).
`--memwallet-coin`	`STRING`	Coin type for Memwallet brainwallets (`bitcoin` or `litecoin`).
`--bip38-enc-privkey`	`ENC-PRIVKEY`	BIP38-encrypted private key to recover.
`--bip38-currency`	`COIN`	Currency for the BIP38 key (e.g., `bitcoin`, `litecoin`, `dash`). Default: `bitcoin`.
`--skip-compressed`	—	Skip compressed key variants.
`--skip-uncompressed`	—	Skip uncompressed key variants.
`--force-check-p2sh`	—	Force checking P2SH SegWit addresses (needed for some altcoin brainwallets).

Search control

Flag	Argument	Description
`--threads`	`COUNT`	Number of worker threads (default: number of logical CPU cores).
`--worker`	`ID/TOTAL`	Divide workload across multiple machines. Each machine runs with a unique ID. Example: `--worker 1/3`. You can assign multiple slices: `--worker 1,2/3`.
`--skip`	`COUNT`	Skip this many initial passwords (to continue an interrupted search without autosave).
`--max-eta`	`HOURS`	Refuse to start if estimated completion time exceeds this value (default: 168 hours / 1 week).
`--no-eta`	—	Disable ETA calculation (skips the initial counting phase).
`--no-dupchecks` / `-d`	—	Disable duplicate password checking to save memory. Specify multiple times for additional effect (up to 4×).
`--no-progress`	—	Disable the progress bar.
`--utf8`	—	Enable Unicode mode; all input must be UTF-8 encoded.
`--performance`	—	Run a continuous performance benchmark (Ctrl-C to exit).

If BTCRecover hangs at “Counting passwords…”, run with --no-dupchecks. For very large search spaces also add --no-eta. See the FAQ for more detail.

Example — multi-machine split

# 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

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

GPU / OpenCL acceleration

GPU acceleration is supported for: Bitcoin Core wallets, Blockchain.com (main and second password), Electrum passwords, BIP39 seeds, and Electrum seeds.

Flag	Argument	Description
`--enable-opencl`	—	Enable OpenCL-based GPU acceleration.
`--opencl-info`	—	List available GPU platform and device names, then exit.
`--opencl-platform`	`ID [ID ...]`	Choose the OpenCL platform(s) to use (default: auto).
`--opencl-devices`	`ID1,ID2,...`	Comma-separated list of device IDs within the chosen platform (default: all).
`--opencl-workgroup-size`	`COUNT [COUNT ...]`	Batch size for OpenCL work groups.
`--enable-gpu`	—	Enable legacy OpenCL GPU acceleration (Bitcoin Core only).
`--global-ws`	`COUNT [COUNT ...]`	OpenCL global work size for `--enable-gpu` (default: 4096).
`--local-ws`	`COUNT [COUNT ...]`	OpenCL local work size; must evenly divide `--global-ws` (default: auto).
`--gpu-names`	`NAME-OR-ID [...]`	Choose specific GPU(s) on multi-GPU systems.
`--list-gpus`	—	List available GPU names and IDs (for `--enable-gpu`), then exit.
`--int-rate`	`RATE`	Interrupt rate for `--enable-gpu`; raise to improve PC responsiveness at the cost of speed (default: 200).

Example — list available OpenCL devices

python btcrecover.py --opencl-info

Example — GPU-accelerated BIP39 seed recovery

python btcrecover.py --bip39 \
  --addrs 1AmugMgC6pBbJGYuYmuRrEpQVB9BBMvCCn \
  --mnemonic "certain come keen collect slab gauge photo inside mechanic deny leader drop" \
  --tokenlist ./tokens.txt \
  --enable-opencl

Autosave and restore

Flag	Argument	Description
`--autosave`	`FILE`	Save progress every 5 minutes to this file. If the file already exists, progress is restored from it.
`--restore`	`FILE`	Restore progress and all options from an autosave file. Must be the only argument on the command line.

Example

# Start a long recovery with autosave
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --autosave ./recovery.sav

# Resume after interruption
python btcrecover.py --restore ./recovery.sav

Output and wallet dumping

Flag	Argument	Description
`--dump-wallet`	`FILE`	After a successful recovery, dump the decrypted wallet to this file.
`--dump-privkeys`	`FILE`	Dump a list of private keys (Electrum-importable format) to this file.
`--possible-passwords-file`	`FILE`	File to save “close match” candidates to (default: `possible_passwords.log`).
`--disable-save-possible-passwords`	—	Disable saving close-match candidates.
`--listpass`	—	List all password combinations to try, then exit without searching.
`--pause`	—	Pause before exiting (useful on Windows to read the output).
`--no-progress`	—	Disable the progress bar display.
`--version` / `-v`	—	Show full version information and exit.
`--disablesecuritywarnings` / `--dsw`	—	Disable security warning messages.
`--beep-on-find`	—	Play an audible alert when the password is found.

Supported Wallets

Command Reference

Examples & Troubleshooting

btcrecover.py Options

Build docs developers (and LLMs) love