Cracking a Bitcoin Wallet with btcrecover in 2026

I work in the crypto self-custody space, and the lost-wallet messages I get almost always start the same way: an old wallet file, a password that was supposed to be unforgettable, and several weekends of guessing by hand.

TL;DR

btcrecover is an open-source Python tool that searches for a forgotten wallet password or a missing BIP 39 seed word, but only when you already know most of the answer. Use the maintained fork at github.com/3rdIteration/btcrecover. The original gurnec/btcrecover has had no commit since 21 December 2017; do not clone it. Run btcrecover offline and never hand your wallet file or seed to someone who contacted you first. If you remember less than half the password, or have only 21 of 24 seed words with no idea where the gaps are, read the stop section before you spend more weekends.

The Situation btcrecover Was Built For

The typical case: someone bought bitcoin years ago, stored the wallet.dat on a drive that sat unpowered for years, and set a password they were sure they would never forget. They have the file. They remember most of the password. They are panicking.

btcrecover was built for this situation.

It is also the situation scammers prey on hardest. Before you touch any technical step below, read this article to the end, especially the safety section. Take your time: 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 owned 7,002 bitcoin locked behind an IronKey drive, which gives users 10 password guesses before it encrypts its contents for good; by January 2021 he had used eight, according to The New York Times. His situation is not a btcrecover problem. A software-encrypted wallet file has no guess limit. You can copy it and try as many passwords as your hardware allows, which is why most recovery stories are far more tractable than his.

What btcrecover Does and Where It Fails

btcrecover is a Python script that runs a guided search against an encrypted wallet file or a partial seed phrase. It tries every plausible variant of the data you already have, and nothing beyond it.

Two paths cover most readers. Path A is password recovery on an encrypted wallet file. The 3rdIteration README lists Bitcoin Core, Electrum 1.x to 4.x, MultiBit Classic and HD, Blockchain.com and MetaMask among the supported formats. You feed btcrecover a list of remembered fragments and it combines 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 candidate words against an address you give it, or against an address database of the chain.

One format note before you start. Bitcoin Core 23.0 (April 2022) made descriptor wallets the default, and descriptor wallets store the wallet file in SQLite instead of the older Berkeley DB format, as the 0.21.0 release notes explain. btcrecover reads both: its Bitcoin Core loader falls back to SQLite when it finds no Berkeley DB master key, and the extract script documentation says the same. The catch is on the Bitcoin Core side: version 30.0 (October 2025) can no longer load old Berkeley DB wallets and migrates them with the migratewallet RPC instead. Keep that in mind for the sweep at the end.

Both paths need something you already know: an encrypted file plus a fragmentary memory, or a near-complete seed. btcrecover cannot help in four cases. All you have is an address, because no consumer hardware can solve the discrete logarithm problem behind it. The wallet file is lost, which is a job for file-recovery tools such as PhotoRec. The seed is written down "somewhere", which is a search problem, not a brute-force problem. Or several seed words are missing and you do not know where they go (the arithmetic is in the seed section).

Be clear with yourself about which problem you have before you spend a weekend on it.

Why gurnec Is Dead and 3rdIteration Won

Older tutorials still tell readers to git clone https://github.com/gurnec/btcrecover. That repository's last commit landed on 21 December 2017, and its install guide still asks for Python 2.7. Nobody has patched it since.

The maintained fork is github.com/3rdIteration/btcrecover. On 11 October 2026 it showed 896 stars and 277 forks on the GitHub API, and its latest commit was dated 17 July 2026. Its installation guide supports Python 3.10 to 3.14 and recommends 3.13. Beyond Bitcoin wallets it also handles SLIP-39 Shamir backups and many altcoin wallets. The ReadTheDocs site (btcrecover.readthedocs.io) is built from the 3rdIteration repository, so the docs and the code match.

You may also see a mrsmookie/btcrecover repository in search results. GitHub does not list it as a fork of either project, it was created on 1 February 2026, and its files are the old gurnec code. Skip it.

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 you own. 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 reads the clipboard, a remote desktop session.

Use a laptop with no funds on it, never your daily driver with its logged-in browser sessions. A spare or an old laptop you can wipe will do. Write a live USB of Linux Mint or Ubuntu with balenaEtcher or dd, boot from it, and do not install. A live session keeps nothing between reboots unless you set up persistence, which in my view makes it the safest environment you can build in an evening. Once the software is installed, go offline: Wi-Fi off, Bluetooth off, ethernet unplugged.

Before the first command, copy the wallet file onto three separate USB sticks, label them, and keep them apart. If a recovery attempt corrupts the file or a USB stick dies, you have backups. Keep the room clean: no phone recording the screen, no cloud-photo backup of your terminal, no spectators. The investment is one evening, and it closes the realistic ways the wallet would otherwise leak.

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, check the Python version:

python3 --version

The installation guide supports Python 3.10 to 3.14 and recommends 3.13. On 3.14 one of the fast cryptography libraries has no prebuilt package yet, so 3.13 is the easier choice.

Next, on a different online machine (your daily laptop, for example), clone the maintained fork and download its dependencies onto a USB stick:

git clone https://github.com/3rdIteration/btcrecover.git
cd btcrecover && git log -1 --format="%cd"
pip download -r requirements.txt -d wheels/

The last commit should be recent. If you see a 2017 date, you cloned the wrong repository. Check the URL. Copy the whole btcrecover/ directory, including wheels/, onto the USB stick.

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

cd ~/btcrecover
python3 -m venv venv
source venv/bin/activate
pip install --no-index --find-links=wheels/ -r requirements.txt

pip installs from the downloaded wheels/ folder, so the offline machine never needs the internet. Build the wheels with the same Python version and the same operating system you run offline, or pip will refuse some of them.

Finally, check the install with python btcrecover.py --version. You should see a version string and no errors. If you see ImportError or ModuleNotFoundError, you probably forgot to activate the virtualenv.

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, or a wallet file from Electrum, MultiBit or Blockchain.com) and you remember most of the password.

btcrecover does not guess blindly. It builds candidates from a token list you write, adds the typos you ask for, and tests each one against the file. For Bitcoin Core it derives a key from each candidate, decrypts the last block of the wallet's encrypted master key, and stops when that block decrypts to valid padding, as the password check in btcrpass.py shows. A wrong password produces anything else.

Write the token list. Open a text file and put each fragment you might have used on its own line. Example for a hypothetical 2018 wallet:

Wallet wallet
2018 18
Marathon marathon
Bordeaux
!

The token file guide explains the two rules that matter most. btcrecover tries every combination of one or more lines, in any order. Tokens on the same line are alternatives and are never tried together, so Wallet wallet covers both spellings without doubling the search. A + at the start of a line marks a token that must appear, and wildcards such as %d (one digit) or %2,3d (two or three digits) fill gaps you only half remember. Read that page in full before you write your list.

Typos are command-line options, not token-file syntax. --typos 2 allows up to two typos per candidate, and you choose the kinds: --typos-capslock tries the whole password with caps lock on, --typos-swap swaps two adjacent characters, and the tutorial lists the rest. Each extra typo multiplies the search, so stay close to what you 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 matters. A search may run for hours or days, and session.dat stores progress every 5 minutes according to the option's own help text in btcrpass.py, so an interruption costs minutes instead of the whole run.

While it runs, watch the speed and the ETA. Bitcoin Core derives the wallet key with SHA-512 repeated at least 25,000 times (crypter.h), and raises the count until one derivation takes about 100 milliseconds on the machine that encrypted the wallet (wallet.cpp). That makes each guess slow. The project's GPU guide measured 70 Bitcoin Core passwords per second on an Intel i7-8750H CPU. At that rate a million candidates take about four hours. If the ETA runs to years, your token list is too broad.

When btcrecover finds the password, it prints it on screen. Do not 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 word is illegible or torn off, and you need to find it. btcrecover ships seedrecover.py for exactly this.

You need two things: the words you have, in order, and at least one address from this wallet. The seedrecover quick start guide asks for an address created early in the wallet's life, plus an address generation limit that covers it. The address lets seedrecover.py check candidate seeds without broadcasting anything. If you have no address at all, an address database of every address used on the chain can stand in. You can build one from your own node or download a prebuilt file on the online machine and copy it across.

Then run it, in the form the project's seed recovery examples use. Leave the missing word out; the script tries every word in every position:

python seedrecover.py \
  --wallet-type bip39 \
  --addrs bc1q... \
  --addr-limit 10 \
  --mnemonic "abandon ability able about above absent absorb abstract absurd abuse access accident account accuse achieve acid acoustic acquire across act action actor add"

The script tries each of the 2,048 words in the BIP 39 wordlist in each gap, derives addresses on the BIP 44, BIP 49 and BIP 84 paths of the first account by default, and compares them with your address. The GPU guide measured 33,000 12-word seeds per second and 160,000 24-word seeds per second on an i7-8750H CPU. At those rates one missing word finishes in minutes. Two missing words in unknown places mean about 1.2 billion candidates for a 24-word seed (276 pairs of positions times 2,048 squared), roughly two hours. Three missing words are about 8.6 billion candidates for each guess of where the gaps are, around 15 hours at 160,000 per second; with the positions unknown, that becomes years.

GPU Acceleration and Token Lists

GPU acceleration is the btcrecover question I hear most, and the answer people expect is usually wrong.

The project's own GPU guide compared an Intel i7-8750H CPU with an NVIDIA GTX 1660 Ti. The table below copies its figures:

GPU pays off most for Bitcoin Core wallet.dat passwords, where each guess runs those thousands of SHA-512 rounds. For a 24-word seed the GPU barely helps, because the work that generates candidate seeds stays on the CPU; the guide says so and warns you not to assume a speed-up, especially with a fast CPU and a slow GPU. Test both ways with --performance before you commit a weekend to drivers.

The two GPU switches are different. --enable-gpu covers Bitcoin Core wallets and extracts only, and --enable-opencl covers BIP 39, Electrum and Blockchain.com, according to the option help in btcrpass.py. On Linux, install your GPU driver, then PyOpenCL (sudo apt install python3-pyopencl, or pip install pyopencl in the virtualenv if the packaged one is too old):

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

The guide says that on Windows and macOS PyOpenCL installs with pip as long as the GPU driver is present, and macOS ships with its drivers. If pyopencl fails to install on Linux, the guide suggests trying an older PyOpenCL release. For the typical "I remember most of my password" case, a CPU run that finishes overnight is often enough.

Never Do These Four Things

If you take nothing else from the article, take this section.

1. Never share your wallet file or seed with anyone who contacted you to "help." The FBI described the pattern in a 2023 public service announcement: fake recovery firms reach victims on social media, messaging apps and comment sections, charge an up-front fee, and then disappear or ask for more. Block the account, report it, and move on.
2. Never upload your wallet file to a cloud service. Not Google Drive, not Dropbox, not WeTransfer, not a Discord attachment. Every upload creates a copy you no longer control. Local USB transfer only.
3. Run btcrecover on a clean Linux live USB, not your everyday Windows or macOS install. My reason: the daily machine has sync clients, backup tools and browser sessions that can copy files without asking, and a live USB has none of them.
4. Pay only on success, never up front. My rule, consistent with the FBI warning above: a real service takes its fee from recovered funds. The same care applies to your recovered password. Do not type it into a browser, a remote desktop session or a cloud-synced terminal, and never post your wallet file on a forum asking for help. Anyone who downloads it can run the same search you are running.

When to Stop the DIY Recovery

There is a moment in every recovery where the right answer is to stop. Knowing that moment protects your funds from the desperation phase, which is when scammers find their best targets.

My rule of thumb is to stop and rethink when any of these is true:

• You have spent three full weekends and worked through your most plausible token lists.
• The ETA btcrecover prints for your token list runs past a year.
• You remember less than half the password's characters and not much of its shape.
• All you have is an address, with no wallet file and no seed words.
• You are starting to consider services that found you in your DMs.

If you stop, you have three options. Wait: your memory is the limiting factor, and a forgotten password sometimes comes back weeks or months later, once the panic drops. Hire a recovery service: Wallet Recovery Services, in business since 2013 by its own account, charges 20% of the wallet's value and nothing if it fails, according to its pricing page. It works from your wallet backup or seed words, so you trust it with the coins. For Bitcoin Core you can limit that trust: btcrecover's extract script pulls out only the encrypted master key, which "does not contain any of your Bitcoin address or private key information". Or accept the loss, and put the effort into new savings secured with a hardware wallet and proper self-custody hygiene.

The wrong answer is to keep trying with no new information and no narrower search. At that point you are gambling with your time.

The Swiss Tax Angle

Two questions Swiss readers always ask.

Is recovered bitcoin a taxable event? Regaining access is not a purchase or a sale, so in my reading no income tax arises. The ESTV working paper on cryptocurrencies (Ziff. 2.2.1 and 2.2.2) says that payment tokens fall under the cantonal wealth tax at their market value at the end of the tax period, that the ESTV publishes values in its Kursliste, and that merely holding them generates no taxable income. See the full framework in the Bitcoin tax in Switzerland guide.

What if you left the coins off your tax returns while you could not reach them? Ask your cantonal tax office how it treats those years, because the paper does not address lost access. If the omission counts as tax evasion, the Steuerharmonisierungsgesetz (StHG Art. 56 Abs. 1bis) waives the penalty for a first self-report, provided no tax authority knew about it and you cooperate while the back tax is set. The back tax itself is still due. A Swiss Steuerberater can walk you through the form.

btcrecover vs Paid Recovery Services

Three rough options for the decision-making moment.

My rule of thumb: for amounts under roughly CHF 50,000 with a near-complete password or seed, DIY with btcrecover is free and keeps your data with you. Above that, when the case is technically recoverable but the search is heavy, a paid service with a success-only fee can be worth its share. 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. The recovery is not over.

Your old wallet file lived on storage that may have been exposed during the years you could not reach it. Your password now sits in your terminal scrollback. Both are weaker than a fresh seed generated on a fresh hardware wallet, so the final step is the sweep.

Set up a new hardware wallet: generate a new 24-word seed, write it on paper, and do not use it for anything else first (see the self-custody setup guide). On the offline machine, open the recovered wallet. An old Berkeley DB wallet.dat needs a Bitcoin Core version before 30.0, or migration with migratewallet in 30.0 and later. Build and sign a transaction that sends the entire balance to a fresh receive address from the hardware wallet, with a fee high enough to confirm in the next block or two. Copy the signed transaction to a USB stick and broadcast it from a separate online device, for example through mempool.space. Never put the offline machine online. Once the transaction confirms, wipe the old wallet file from every backup USB, format the sticks, and throw away the labels. Never reuse the old seed or password.

You have turned "bitcoin lost behind a password I half-remembered" into "bitcoin under a fresh hardware-wallet seed I backed up properly." That is the end state, and the rest is paperwork.

Related Reading

• Bitcoin self-custody guide: the hygiene for your sweep destination
• BIP 39 brute-force attacks: what makes a seed recoverable, and what does not
• Bitcoin inheritance: the sister problem to recovery
• Weak entropy in Coldcard wallets: when a firmware bug made seeds recoverable by attackers
• 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, check that you cloned the maintained 3rdIteration fork, and never share your seed phrase or wallet file with anyone who contacted you offering "help." For a complex Swiss tax question, consult a Swiss-licensed Steuerberater.