Installation

BTCRecover is a Python script with no installer. You download it, install Python and the required packages, then run it from a terminal.

On Windows, use python in commands. On Linux and macOS, use python3. All examples on this page use python3 to match Linux/macOS defaults.

Download BTCRecover

Download the latest zip from GitHub and unzip it to a folder of your choice:

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

# Or download and unzip manually
# https://github.com/3rdIteration/btcrecover/archive/master.zip

There is no installer. The main scripts — btcrecover.py and seedrecover.py — are in the root of the unzipped folder.

Install Python 3

Only Python 3.9 and later are supported. Python 3.12 is recommended because it has the simplest module installation across all platforms.

Windows
Linux
macOS
Android (Termux)

Download the latest Python 3.12 installer from python.org/downloads/windows.
Run the installer. On the first screen, check “Add Python to PATH” before clicking Install.
Choose the 64-bit (x86-64) installer for modern PCs.

Windows limits the number of threads to 64. If your system has more logical cores than this, run BTCRecover on Linux instead.

Most modern distributions include Python 3. Install any missing components:

# For Ubuntu/Debian — install pip and tkinter (tkinter is needed for the seedrecover GUI)
sudo apt install python3-pip python3-tk

# If cffi fails to build
sudo apt install libffi-dev

# If python3-pip has no installation candidate, enable universe first
sudo add-apt-repository universe
sudo apt install python3-pip

Install Homebrew, then use it to install Python and the coincurve build requirements:

# 1. Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install Python and build dependencies
brew install autoconf automake libffi libtool pkg-config python python-tk

# 3. (Optional) Install Rust — needed for requirements-full.txt modules
curl https://sh.rustup.rs -sSf | sh

After installing Python via Homebrew, use version-specific commands like python3.12 and pip3.12 instead of python3 and pip3.

Termux support is experimental. Install Termux (use the version from their site, not Google Play), then run:

pkg install python-pip git autoconf automake build-essential libtool pkg-config binutils-is-llvm rust

Do not run pip install --upgrade pip in Termux — it will fail and is unnecessary. Your phone may also lack sufficient cooling for long searches.

Install Python packages

From inside the btcrecover directory, install the required packages.Essential packages (Bitcoin and Ethereum wallet support):

pip3 install -r requirements.txt

Full packages (all supported wallet types):

pip3 install -r requirements-full.txt

If you get an error: externally-managed-environment message on newer Linux distributions (Ubuntu 23.04+, Debian 12+), add --break-system-packages:

pip3 install -r requirements.txt --break-system-packages

If you use Python for other projects, consider using a virtual environment instead to avoid conflicts.

If you are running Python 3.13 and get a build error, set this environment variable before running the pip command:

export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
pip3 install -r requirements.txt

Fix RIPEMD160 on Linux and macOS (if needed)

As of OpenSSL v3 (released late 2021), RIPEMD160 is part of the “Legacy” provider and may be disabled by default on Linux and macOS. BTCRecover includes a pure-Python fallback, but it runs at roughly one-third the speed of the native implementation.Check whether native RIPEMD160 is working:

python3 check_ripemd160.py

If the script reports that RIPEMD160 is not available, you need to enable the OpenSSL legacy provider. An example configuration file is available at docs/example_openssl.cnf in the repository.

A video walkthrough of this fix is available in the BTCRecover YouTube playlist.

Test your installation

Run the full test suite to confirm everything is working:

python3 run-all-tests.py -vv

This takes a few minutes. It should complete without errors. Any failures indicate missing packages or a configuration issue for that wallet type.

Wallet-specific package requirements

The requirements.txt file covers Bitcoin and Ethereum wallets. For other wallets, you may need additional packages. The simplest option is to install everything:

pip3 install -r requirements-full.txt

Key additional packages and the wallets that need them:

Package	Required for
`coincurve`	Electrum 2.8+ encrypted wallets, BIP-39 passphrases, Bither
`pycryptodome`	20x speedup for Bitcoin Core, MultiBit, Electrum, Blockchain.com (not strictly required)
`py_crypto_hd_wallet`	Avalanche, Cosmos, Polkadot, Solana, Stellar, Tezos, Tron, Secret Network
`shamir-mnemonic`	SLIP-39 wallets
`groestlcoin_hash`	Groestlcoin BIP-39 wallets
`eth-keyfile`	Ethereum UTC Keystore files
`ecdsa`	BIP-38 encrypted paper wallets
`pynacl`, `bitstring`	Helium BIP-39 wallets

For py_crypto_hd_wallet on Windows, you must first install the Microsoft Visual C++ Build Tools.

Get Started

Password Recovery

Seed Recovery

Advanced

Wallet-specific package requirements

Build docs developers (and LLMs) love

Get Started

Password Recovery

Seed Recovery

Advanced

​Wallet-specific package requirements

Build docs developers (and LLMs) love

Wallet-specific package requirements