Install BTCRecover and check your setup

Get the maintained project

Use the 3rdIteration repository for the maintained BTCRecover project. Download its source ZIP using GitHub’s Code menu, or clone it if Git is installed. Keep a record of the revision you use.

git clone https://github.com/3rdIteration/btcrecover.git
cd btcrecover

The original gurnec repository is part of the project’s history. Its legacy installation instructions are not the starting point for this guide.

Use a separate Python environment

The maintained installation guide currently recommends Python 3.13. Check its version notes before choosing a newer release, because native dependencies can lag behind Python releases. The following examples assume Python 3.13 is already installed.

On Windows Command Prompt:

py -3.13 -m venv .venv
.venv\Scripts\activate.bat
python --version
python -m pip install -r requirements.txt

On macOS or Linux:

python3.13 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install -r requirements.txt

If your Python executable has another name, adapt that first command. Use the activated environment for every subsequent command. Some wallet formats need extra packages described in the upstream installation guide.

Check the installation

python btcrecover.py --help
python run-all-tests.py -vv

Read the test summary. Failed tests or missing dependencies need attention before a real recovery. Some tests may be skipped when optional components are absent; check that the requirements for your particular wallet are installed.

Next, run the small tokenlist demonstration. It should display exactly two candidates, with no wallet required.

Prepare before going offline

Download the code, dependencies, and reference material before taking your recovery computer offline. For an actual wallet, use a trusted local environment and a copy of your backup. Keep outputs and candidate files away from cloud-synced folders.

GPU acceleration is optional and format-dependent. Establish a correct CPU search first, then follow the project’s separate GPU setup instructions if your wallet is supported.