ethereum-wallet-recovery: Open-Source Wallet Recovery for ETH

What Is ethereum-wallet-recovery?

ethereum-wallet-recovery is a Python 2.7 Ethereum keystore password recovery CLI published by NamKhoa-07, and it is one of the best Wallet Recovery CLI Tools for Ethereum wallet owners recovering lost keystore v3 passwords. The project is built from pyethrecover and pyethereum, and the README shows a split workflow: generate.py creates candidate wordlists while recovery.py tests them against a JSON keystore with multithreading and 50MB wordlist rollover. If you remember fragments of the password, this is a focused recovery utility rather than a generic cracking suite.

Quick Overview

The repository snapshot does not expose a license badge, star count, or tagged release, so those fields are unknown from the provided page text.

Who Should Use ethereum-wallet-recovery?

• Wallet owners with partial password memory who remember a few words, prefixes, suffixes, or character classes and need a deterministic search path instead of random guessing.
• Incident responders and recovery specialists handling their own Ethereum keystore backups who need a local CLI that can test candidate passwords offline.
• Security engineers and indie hackers validating whether an old keystore can be recovered before they discard a backup or migrate funds.
• Forensics teams running isolated legacy environments that can tolerate Python 2.7 and old Ethereum dependencies inside a throwaway VM.

Not ideal for:

• Modern Python 3-only stacks that cannot easily pin Python 2.7, ethereum==2.1.5, and the older dependency chain.
• Users expecting seed phrase recovery from a wallet app, because ethereum-wallet-recovery is built around keystore v3 JSON password recovery.
• Anyone trying to crack third-party wallets without authorization, since the tool is only defensible for wallets you own or are explicitly allowed to assess.

Key Features of ethereum-wallet-recovery

• Two-stage workflow — generate.py builds candidate lists and recovery.py consumes them, so you can precompute search space once and reuse it across multiple recovery attempts. That separation matters when you want to tune word ordering, prefix chains, or numeric ranges before hammering the keystore.
• Multithreaded password testing — the recovery script accepts -t N and uses parallel jobs to test candidates faster on multi-core CPUs. The design is CPU-bound, which is appropriate for offline keystore checking where the bottleneck is candidate enumeration and hash verification.
• Wordlist generation from multiple sources — the generator accepts comma-separated words with -w, file input with -i, and ASCII-derived candidates with -a. It also supports -min and -max to bound word length, which reduces waste when you already know the password shape.
• Prefix and suffix constraints — -s and -e let you inject starting or ending words from files, which is useful when the remembered phrase has a fixed opening or trailing fragment. That is more efficient than brute-forcing a full mask when you know the wallet owner habitually uses the same prefix.
• Brute-force masks for bounded search spaces — -b ASCII can sweep the whole ASCII table, while custom symbol sets like 1234567890 or @#!$%^&*( narrow the search to a smaller alphabet. The -l flag defines exact brute-force length, which keeps the candidate space explicit and auditable.
• Legacy Ethereum compatibility focus — the dependency list includes rlp==0.6.0, py_ecc==1.1.3, and ethereum==2.1.5, which points to a tool optimized for older Ethereum wallet formats rather than a broad modern wallet suite. That narrow scope reduces ambiguity when you are dealing with a single keystore v3 JSON file.
• Wordlist rollover at 50MB — generated wordlists split into wordlist_01.txt, wordlist_02.txt, and so on once they hit 50MB. That keeps individual files manageable for tooling, storage, and repeated recovery runs.

ethereum-wallet-recovery vs Alternatives

Pick [John the Ripper] when you need a general-purpose audit framework that covers many formats, not just Ethereum keystore files. Pick [Hashcat] when your recovery space is large enough that GPU throughput matters more than a purpose-built CLI. Pick pyethrecover when you want the upstream reference implementation and do not need the extra packaging or the generator script.

For adjacent workflows, DataHaven makes sense when you need to store the recovered keystore safely, and enveil fits when you want to encrypt artifacts at rest before they leave the recovery box. For a broader view of adjacent security utilities, browse all Security Tools.

How ethereum-wallet-recovery Works

ethereum-wallet-recovery splits the problem into candidate creation and candidate verification. generate.py enumerates a finite search space from words, files, ASCII tables, and length bounds, then writes the output in chunks so you do not end up with a single giant file that is awkward to inspect or transfer. recovery.py reads the keystore file, takes either a generated wordlist or a brute-force mask, and tests each candidate against the Ethereum v3 JSON password check using multiple worker threads.

The design choice here is simple: keep the recovery path offline, deterministic, and explicit. That is why the CLI exposes -W for the wallet file, -w for the wordlist, -s and -e for fragment constraints, and -b plus -l for exact brute-force masks. The trade-off is that the project stays tied to Python 2.7 and legacy Ethereum libraries, which is fine for an isolated recovery VM but not great for a modern long-lived workstation.

python generate.py -w 'alpha,beta,gamma' -min 6
python recovery.py -W UTC--2017-07-12T00-06-42.772050600Z--f5751c906091b98be2a6be5ce42c573d704aedab -w wordlist_01.txt -t 8

The first command builds a candidate list from three tokens and filters out short outputs. The second command tests that list against a keystore v3 JSON file using eight threads, which is the fastest path when you already have a plausible word family.

Pros and Cons of ethereum-wallet-recovery

Pros:

• Narrow keystore focus means the command set is easy to reason about when you only care about Ethereum v3 JSON recovery.
• Two-script architecture keeps candidate generation separate from testing, which makes repeated recovery attempts more efficient.
• Prefix, suffix, and mask support covers the most common human memory patterns without requiring a full combinatorial search.
• Multithreaded execution improves throughput on CPU-bound recovery jobs, especially when the candidate space is already constrained.
• Legacy dependency pinning makes the runtime predictable once the environment is built, which helps when you need reproducible recovery results.
• Offline workflow keeps sensitive wallet files off remote services and avoids uploading secrets to a third-party API.

Cons:

• Python 2.7 is mandatory according to the README, which forces an older runtime and complicates setup on modern machines.
• Old Ethereum package versions increase the chance of dependency friction inside current Linux distributions and Windows environments.
• No GPU or distributed mode means it will lose to Hashcat-style hardware acceleration on very large search spaces.
• Limited wallet scope makes it useless for many modern wallet formats, seed phrases, and non-Ethereum recovery cases.
• Recovery quality depends on user memory because the tool is most effective when you can narrow the search with real clues.

Getting Started with ethereum-wallet-recovery

Start by building an isolated Python 2.7 environment, installing the legacy dependencies, and then testing a small candidate set against a copy of your keystore file. If you are handling a sensitive backup, store the original in DataHaven and keep the working copy encrypted with enveil before you begin recovery.

sudo apt-get install libssl-dev build-essential automake pkg-config libtool libffi-dev libgmp-dev pandoc libreadline-dev zlib1g-dev curl git
curl https://pyenv.run | bash
pyenv install 2.7.14
pyenv global 2.7.14
pip install setuptools --upgrade
pip install joblib pypandoc markdown rlp==0.6.0 py_ecc==1.1.3 ethereum==2.1.5
python generate.py -w 'alpha,beta,gamma'
python recovery.py -W UTC--2017-07-12T00-06-42.772050600Z--f5751c906091b98be2a6be5ce42c573d704aedab -w wordlist_01.txt -t 4

After the install completes, generate.py writes wordlist_01.txt in the current directory and rolls over once the file reaches 50MB. recovery.py then tests the generated candidates against the keystore file, so you should start with the smallest plausible search space before moving to larger masks or ASCII sweeps.

Verdict

ethereum-wallet-recovery is the strongest option for recovering legacy Ethereum keystore v3 passwords when you already know part of the phrase and can tolerate Python 2.7. Its best strength is the split generator/tester workflow, which keeps the search space explicit and reproducible. The main caveat is the aging dependency stack, so use it in an isolated environment and prefer it only for owned wallets with real recovery clues.