Cracking a Bitcoin Wallet with btcrecover in 2026

TL;DR

btcrecover is an open-source Python tool that brute-forces a Bitcoin wallet password or fills in a missing BIP-39 seed word, but only when you already have most of the answer. Use the maintained fork at github.com/3rdIteration/btcrecover. The original gurnec/btcrecover was abandoned on 2017-12-21 and should not be cloned. Run it offline, never share your wallet file, and no reputable recovery service ever asks for your seed phrase. If you have fewer than half the password characters or fewer than 22 of 24 seed words, read the stop section before you burn three weekends.

The Phone Call That Always Starts the Same Way

A friend's brother sends a message at 11:47 on a Sunday night. He bought 4 BTC in 2017. Stored the wallet.dat on a NAS he hasn't powered on since 2019. The password? Something he thought he'd never forget. He's been guessing for three weekends. Last attempt locked his keyboard layout into an infinite loop. He has the file. He has 75% of the password. He's panicking.

This is the situation btcrecover was built for.

It is also the situation that scammers prey on most ruthlessly. Before any of the technical steps below, read this article end-to-end, especially the safety section. Recovery is not a race. The Bitcoin will still be there next week. The person who messages you on Telegram offering to recover it for an upfront fee will not.

A note on the most famous "lost Bitcoin" story. Stefan Thomas, whose 7,002 BTC (reported by the New York Times, January 2021) are locked behind an IronKey hardware password, is the emotional anchor for every article in this category. Thomas did not use btcrecover and his situation is not a btcrecover problem. IronKey self-destructs after 10 wrong attempts; software-encrypted wallet files do not. Most recovery stories are far more tractable than his.

What btcrecover Does and Where It Fails

btcrecover is a Python script that performs guided brute force against an encrypted wallet file or a partial seed phrase. Not a magic wand. A structured search engine that tries every plausible variant of the data you already have.

Two paths cover most readers. Path A is password recovery on an encrypted wallet file: a Bitcoin Core wallet.dat, an Electrum wallet, an encrypted JSON export from Blockchain.info, Bitpay, MultiBit, or a keystore from MetaMask or Trust Wallet. You feed btcrecover a list of remembered fragments and it permutes them with optional typos until one decrypts the file. Path B is seed-phrase recovery with one or two missing words. The companion script seedrecover.py tests every BIP-39 word in the unknown slot against the address list you give it, or against an AddressDB snapshot of the chain.

One format caveat before you start. btcrecover's wallet.dat path targets legacy Bitcoin Core wallets in Berkeley DB format. Descriptor wallets created with Bitcoin Core 23 or later use sqlite (default since 2022) and a different encryption flow. btcrecover does not currently support sqlite descriptor wallets, so confirm your wallet format with bitcoin-cli getwalletinfo before you start.

Both paths need something you already know. An encrypted file plus a fragmentary memory, or a near-complete seed. btcrecover cannot help if all you have is an address (the discrete logarithm problem is not solvable on consumer hardware in any human lifetime), or a wallet file you cannot locate at all (use file-recovery tools like Recuva or PhotoRec), or a seed phrase you wrote down "somewhere" (the seed is the wallet; you have a search problem, not a brute-force problem), or a 12-word seed with three or more missing words (the 8.5 billion-combination search times the address-derivation cost sits beyond consumer GPU clusters).

Be honest about which problem you have before you spend a weekend on it.

Why gurnec Is Dead and 3rdIteration Won

If you Google "btcrecover" in 2026, the top organic result is still the ReadTheDocs tutorial. Below it is the original gurnec/btcrecover GitHub repository. Below that, a popular Medium tutorial that walks readers through git clone https://github.com/gurnec/btcrecover. All three guide you toward an abandoned repository.

gurnec/btcrecover's last commit was on 2017-12-21. Python 2.7 references. Wallet formats from before SegWit was widely supported. No security patches. If you clone it in 2026, half the commands will silently fail or produce wrong results.

The actively maintained 2026 fork is github.com/3rdIteration/btcrecover. 846 stars, 265 forks (as of 2026-05-13). Last commit 2026-05-01, multiple commits per week through April. Python 3.11 and 3.12 supported. Wallet coverage spans Electrum 4, Sparrow (partial), MetaMask, Trust Wallet, Phantom, SLIP-39 Shamir backups, and 20-plus altcoin chains. Altcoin support is irrelevant if you're recovering Bitcoin, but it confirms the fork is alive. The ReadTheDocs site (btcrecover.readthedocs.io) is built from 3rdIteration, not gurnec; the docs URL is misleading, but the underlying source is the maintained fork.

You may also see a mrsmookie/btcrecover fork on Google. It is a 3-star personal mirror that has not diverged meaningfully from the dead gurnec code. Skip it. Save yourself the detour.

Build the Offline Workstation First

Before any code runs, you need a machine that cannot leak the data you are about to handle. Your wallet.dat or seed phrase is, for the next few hours, the most sensitive file on your computer. Anything that exposes it to the network is a way to lose your Bitcoin: a screen-recording app, a cloud-sync folder, a browser extension that scrapes the clipboard, a remote desktop session.

Use a laptop with no funds on it. Not the daily-driver machine with your everyday browser sessions, but a spare, an old work laptop you can wipe, or a fresh USB-boot. Burn a live USB of Linux Mint or Ubuntu with Balena Etcher or dd, boot from it, and do not install. Live USB means nothing persists between reboots, which is the safest environment you can build in an evening. The moment dependency installation is done, go to airplane mode. Wi-Fi off, Bluetooth off, ethernet unplugged. If you absolutely cannot work offline, at minimum disconnect during the brute-force phase.

Before the first command, make three copies of the wallet file onto three separate USB sticks, label them, and keep them apart. If a recovery attempt corrupts the file or one USB dies in three weeks, you have backups. And keep the room clean: no phone running screen recording, no cloud-photo backup of your terminal, no spectators. The investment is one evening, and it blocks every realistic way you would otherwise leak the wallet to an attacker.

Install btcrecover Step by Step

You are on the offline machine. Wi-Fi is off. You have three labelled backups of the wallet file.

First, confirm Python 3.11 or 3.12:

python3 --version

If you see 3.10 or earlier, install a newer Python from your offline distribution's package manager. Python 3.13 may work but is not officially supported by 3rdIteration as of 2026-05-13.

Next, clone the maintained fork onto a USB stick from a different online machine (your daily laptop, for example):

git clone https://github.com/3rdIteration/btcrecover.git
cd btcrecover && git log -1 --format="%cd"

The last commit should be within the last few weeks. If you see 2017, you cloned the wrong repository. Check the URL. Copy the btcrecover/ directory onto a USB stick.

Move the USB to the offline machine, copy btcrecover/ to the home folder, then:

cd ~/btcrecover
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

pip cannot reach the internet because you are offline. Two options. The safer one: pre-download all dependencies on the online machine with pip download -r requirements.txt -d wheels/, copy wheels/ over, then pip install --no-index --find-links=wheels/ -r requirements.txt. The faster one: temporarily enable Wi-Fi just for the pip install, then immediately re-disable it before touching the wallet file.

Finally, verify the install with python btcrecover.py --version. You should see a version string and no errors. If you see ImportError or ModuleNotFoundError, the virtualenv probably is not activated.

Cracking wallet.dat When You Half-Remember the Password

This is the common case. You have an encrypted wallet file (wallet.dat from Bitcoin Core, an encrypted JSON keystore from Blockchain.info, MultiBit, or a modern web wallet) and you remember most of the password.

btcrecover does not "guess" your password. It generates candidates from a token list you write, applies typos and capitalisation rules, and tries each one against the encrypted file's checksum. Every correct decryption produces a recognisable plaintext header (mainwallet, an address pattern, a known JSON structure); every wrong one produces gibberish. btcrecover stops on the first hit.

Write the token list. Open a text file. On separate lines, list every fragment you might have used. Example for a hypothetical 2018 wallet:

Wallet
2018
Marathon
!
Bordeaux
14

That gives btcrecover six tokens to permute. Add modifier directives where useful:

%t Wallet
%t Marathon
%t Bordeaux
2018
14
!

%t enables typo permutations on the line below it. Other directives include %p for password length range, %n for number patterns, and %c for capitalisation. The 3rdIteration ReadTheDocs covers the full token-list grammar. It is the one place the docs are genuinely indispensable. Smaller search space means faster recovery. Six fragments with two typos each takes hours; twelve fragments with four typos can take weeks. Be tight with what you actually remember.

Then run btcrecover with --autosave:

python btcrecover.py \
  --wallet ~/recovery/wallet.dat \
  --tokenlist ~/recovery/tokens.txt \
  --autosave ~/recovery/session.dat \
  --typos 2 \
  --typos-capslock --typos-swap

Autosave is essential. A brute force may run for hours or days, and without session.dat every interruption costs you the entire elapsed search.

While it runs, watch the keys/sec rate. Bitcoin Core's legacy wallet derives the encryption key with at least 25,000 SHA-512 iterations (EVP_BytesToKey, benchmarked higher on faster machines and the actual count is stored in the wallet). On a modern laptop CPU, expect 50 to 500 keys/sec for wallet.dat. Multiply by your search-space size for a time estimate. If the answer is in years, your token list is too broad.

When btcrecover finds the password, it prints it to stdout. Do not immediately use it to unlock the wallet on a connected machine. Copy it onto paper, close btcrecover, and move to the post-recovery sweep.

Brute-forcing One Missing BIP-39 Word

Rarer case, higher emotional load. You have a notebook with 23 of 24 (or 11 of 12) BIP-39 seed words, one slot is illegible or torn off, and you need to find which word goes there. btcrecover ships seedrecover.py for exactly this.

Write out the seed with the missing slot marked. Example for a 24-word seed:

1. abandon  2. ability  3. able  4. about  5. above  6. absent
7. absorb   8. abstract 9. absurd 10. abuse 11. access 12. accident
13. account 14. accuse  15. achieve 16. acid 17. acoustic 18. acquire
19. across  20. act     21. action 22. actor 23. ?       24. add

You need two things: the index of the missing slot (here, 23), and at least one public address derived from this wallet. The address lets seedrecover.py verify candidate seeds without ever broadcasting a transaction. Any old destination address from your wallet's history works. If you have nothing on hand, an AddressDB snapshot (a pre-computed file of all on-chain addresses) covers it; download it on the online machine and copy across.

Then run:

python seedrecover.py \
  --mnemonic "abandon ability able about above absent absorb abstract absurd abuse access accident account accuse achieve acid acoustic acquire across act action actor ? add" \
  --addresses bc1q... \
  --autosave seed-session.dat

The script iterates every BIP-39 word in the unknown slot, derives the standard paths (m/84'/0'/0'/0/0 for Native SegWit, m/49'/0'/0'/0/0 for nested SegWit, m/44'/0'/0'/0/0 for legacy), and matches against your verifying address. With one missing word and a known address, this takes under 10 minutes on a modern laptop. With two, the search space becomes 2048 squared (about 4.2 million combinations); expect several hours. With three, you are looking at 8.5 billion combinations, which is practically out of reach without an AddressDB-backed search on a much bigger machine.

GPU Acceleration and Token Lists

GPU acceleration is the most-asked btcrecover question and the most-misunderstood feature.

GPU helps with Bitcoin Core wallet.dat password recovery. The key derivation parallelises well across many GPU cores. A desktop GPU like an RTX 3060 typically runs 10 to 100 times faster than a laptop CPU on btcrecover workloads, depending on the wallet format and the kernel. GPU does not meaningfully help BIP-39 seed-phrase recovery. The bottleneck there is BIP-32 child-key derivation and address generation (SHA-256 + RIPEMD-160 in serial steps), and for one or two missing words a CPU is fast enough. Don't waste a weekend installing CUDA for seedrecover.py.

On Linux, install the NVIDIA driver and CUDA toolkit from your distribution's package manager, then in the btcrecover venv:

pip install pyopencl
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --enable-gpu

If pyopencl fails to install, you likely have a kernel-driver mismatch. The fastest fix is a fresh CUDA + driver pairing on the offline Ubuntu live USB.

On Apple Silicon (M1 through M4), GPU acceleration is fragile in 2026. pyopencl builds break against modern macOS and Apple's Metal backend is not supported upstream. Fall back to CPU on Apple hardware. For the typical "I remember most of my password" case, CPU finishes in hours anyway.

Never Do These Four Things

This is the only section that matters if you take nothing else from the article.

1. Never share your wallet file or seed with anyone offering to "help." No legitimate recovery service asks for your seed phrase. The pattern is universal. A stranger DMs you on Telegram, Twitter / X, Reddit, or YouTube, offering to recover your wallet for an upfront fee. They want the wallet file, they extract whatever is recoverable, and they disappear with the funds. Block. Report. Move on.
2. Never upload your wallet file to a cloud service. Not Google Drive, not Dropbox, not WeTransfer, not a Discord attachment. Every cloud upload creates a copy you no longer control. Local USB transfer only.
3. Run btcrecover on a clean Linux live USB, not Windows. OneDrive, Defender, and several third-party AV products will quarantine or upload files matching wallet patterns.
4. Pay only on success, never up front. The legitimate model is percentage on success, taken from recovered funds in escrow. Upfront fees are a 100% scam signal in this industry. The same rule applies to your recovered password: do not type it into a browser, RDP session, or any cloud-synced terminal, and never publish your wallet file on a forum asking for help. Even with the address redacted, the file's metadata can identify which addresses it controls, and everyone who downloads the post can race you to the recovered key.

When to Stop the DIY Recovery

There is a moment in every recovery where the right answer is to stop. Knowing that moment saves your sanity and protects your funds from the desperation phase, when scammers convert their highest-value marks.

Stop and reconsider if you have spent three full weekends and burned through your most plausible token-list permutations, or if your estimated search-space size divided by your keys/sec rate exceeds one calendar year, or if you are working from less than 50% of the password's characters and less than 60% of its general shape, or if all you have is an address with no wallet file and no seed-phrase fragments (the funds are mathematically out of reach in that case), or if you are starting to consider services that found you in your DMs.

If you stop, you have three options. Wait: your memory is the rate-limiting variable, and the exact password sometimes surfaces weeks to months later, once panic has dropped and budget reality has set in. Hire a vetted Swiss-licensed firm: for high-value cases (above CHF 50,000 equivalent), Sygnum and Crypto Finance can engage on institutional custody and recovery work under NDA; they charge percentages on success and never ask for your seed phrase. Accept the loss: Bitcoin's design includes a small percentage of lost coins as a feature, not a bug, and the capital you would otherwise spend on weeks of recovery effort is often better deployed on new positions secured with a hardware wallet and proper self-custody hygiene.

The wrong answer is to keep trying with no new information and no new search-space narrowing. At that point you are not recovering Bitcoin. You are gambling with your time.

The Swiss Tax and Fiduciary Angle

Two questions Swiss readers always ask.

Is recovered Bitcoin a taxable event? No. Recovery itself is not a realisation event; you are regaining access to property you already owned. The Bitcoin remains your private movable property and is subject to annual Vermögenssteuer at the 31 December ESTV Kursliste value, exactly as it would have been if the wallet had been continuously accessible. There is no income-tax event, no capital-gains event under private investor status, no gift event. See the full framework in the Bitcoin tax in Switzerland guide. If you have been omitting the lost Bitcoin from your wealth-tax declarations during the lost-access period, that is a separate compliance matter. The Swiss self-disclosure regime (Selbstanzeige) allows a one-time penalty-free correction; an accountant or a cantonal Steuerberater can walk you through the form.

Who can I hire if DIY fails? Sygnum (Zurich, FINMA-licensed) and Crypto Finance (Zug, FINMA-licensed, part of Deutsche Börse Group) are the two Swiss institutional options. Both engage on institutional custody and digital-asset recovery work under NDA, both charge percentages on success, and neither asks for your seed phrase. Individual lost-key engagements are rare and case-by-case for both firms, so call before assuming they handle your scenario. For smaller cases (below roughly CHF 50,000), most reputable firms will decline the engagement; the operational cost exceeds the percentage they can charge. Small recoveries are DIY or nothing.

Avoid any service that asks you to mail or upload your seed phrase, charges an upfront retainer "for analysis", promises a fixed percentage success rate without seeing your specific case, or found you on Telegram, Twitter / X, Reddit, or YouTube.

btcrecover vs Commercial Recovery Services

Three rough options for the decision-making moment.

For amounts under roughly CHF 50,000 with a near-complete password or seed, DIY with btcrecover is faster, free, and safer than any third-party engagement. Above that threshold, where your situation is technically recoverable but operationally heavy, a vetted Swiss firm is worth the percentage. Anything routed through a stranger's DMs is the scam path. The only safe response is silence.

Sweep the Recovered Funds Immediately

You ran btcrecover. It printed the password. You opened the wallet on the offline machine. The balance is there. The recovery is not over.

Your old wallet file has lived on storage that may or may not have been compromised over the lost-access period. Your password is now in your terminal scrollback. Both are lower-security artifacts than a fresh seed generated on a fresh hardware wallet, so the final mandatory step is the sweep.

On the same offline machine, initialise a hardware wallet that has never been online: generate a new 24-word seed, write it on paper, and do not use it for anything else first (see the hardware wallet setup walk-through for the canonical hygiene). Open the recovered wallet, generate a new receive address on the hardware device, and send the entire balance to that address using a fee that confirms in one block. Verify the receive on a block explorer from a separate online device (never put the offline machine online), then wipe the old wallet file from every backup USB, format the USBs, and dispose of the labels. The old seed and password are dead capital. Never reuse them.

You have converted "Bitcoin lost behind a password I half-remembered" into "Bitcoin under a fresh hardware-wallet seed I generated offline and backed up properly." That is the end state. Everything else is paperwork.

Related Reading

• Bitcoin self-custody guide: the canonical hygiene for your sweep destination
• BIP-39 seed-phrase security: what makes a seed recoverable in the first place
• Bitcoin inheritance planning: the structural sister problem to recovery
• Bitcoin and CVE-2023-50428 (Libbitcoin weak entropy): when bad entropy creates recoverable wallets without the owner's consent
• Bitcoin tax in Switzerland: how recovered Bitcoin shows up on your declaration

Disclaimer

This article is educational content for Bitcoin holders managing self-custody. It is not legal, financial, or tax advice. Bitcoin recovery is a high-stakes operation. Make three offline backups of the wallet file before any command runs, verify the maintained 3rdIteration fork before cloning, and never share your seed phrase or wallet file with anyone offering "help." For high-value cases or any complex Swiss tax question, consult a FINMA-supervised firm and a Swiss-licensed Steuerberater respectively.