Skip to main content

​
Prerequisites

The tool is designed for zero-configuration installation, but ensure you meet these minimal requirements:

Python 3.8+

The launcher scripts will attempt to install Python automatically if missing

USB Debugging

Must be enabled on the target Android device (Settings → Developer Options → USB Debugging)

Git

Required to clone the repository (or download as ZIP)

Internet Connection

Needed for initial setup to download dependencies and ADB tools
The launcher scripts (start.bat and start.sh) handle all dependency installation automatically. No manual configuration is required.

​
Installation by Platform

​
Windows Installation

1

Clone the Repository

Open Command Prompt or PowerShell and clone the repository:
git clone https://github.com/cedroid/whatsapp-forensic-tool.git
cd whatsapp-forensic-tool
2

Run the Launcher

Double-click start.bat or run it from the command line:
start.bat
The launcher will automatically:
  • Check for Python installation (opens download page if missing)
  • Create a virtual environment in venv/
  • Install all Python dependencies from requirements.txt
  • Download ADB platform tools for Windows
  • Launch the application
3

Verify Installation

If successful, you’ll see the main menu:
===========================================
  WhatsApp Backup Forensic Tool Launcher
===========================================
[*] Activating virtual environment...
[*] Checking dependencies...
[*] Starting Application...

Main Menu
1. Scan Connected Devices
2. Dump Backups from Device
3. Decrypt Existing Backup
4. View Decrypted Database
5. Export Chats
6. Deploy to Termux (Downloads)
7. Exit
If Python is not installed, the script will open the Python download page at https://www.python.org/downloads/. Install Python with “Add to PATH” enabled.

​
Understanding the Launcher Scripts

​
Windows Launcher (start.bat)

The Windows launcher performs these operations: 
# Check Python installation
python --version >nul 2>&1

# Create virtual environment if not exists
if not exist "venv" (
    python -m venv venv
)

# Activate virtual environment
call venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run application
python main.py

​
Linux/macOS Launcher (start.sh)

The Unix launcher includes automatic Python installation: 
# Check for Python 3
if ! command -v python3 &> /dev/null; then
    # Linux: Install via apt
    sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip
    
    # macOS: Prompt for Homebrew installation
    # brew install python3
fi

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies and run
pip install -r requirements.txt
python main.py

​
Termux Launcher (same start.sh)

The script detects Termux automatically: 
# Detect Termux environment
if [[ -n "$PREFIX" && "$PREFIX" == *"com.termux"* ]]; then
    # Setup storage access
    termux-setup-storage
    
    # Install Python via Termux packages
    pkg update -y && pkg install -y python
    
    # Install dependencies directly (no venv in Termux)
    pip install -r requirements.txt
    python main.py
fi

​
Automatic Dependency Installation

The tool automatically installs these Python packages:
PackagePurpose
pycryptodomeAES-GCM encryption/decryption
requestsDownload ADB platform tools
richTerminal UI with colors and progress bars
tqdmProgress bars for file operations
thefuzzFuzzy search for chat filtering
All dependencies are installed in an isolated virtual environment (except on Termux) to avoid conflicts with system packages.

​
ADB Setup (PC Only)

On PC platforms, the tool automatically downloads ADB platform tools: 
# From device_manager.py:53-66
def download_adb(self):
    url = self.ADB_URLS.get(self.os_type)
    if not url: return
    print_info(f"Downloading ADB for {self.os_type}...")
    try:
        response = requests.get(url, stream=True)
        with zipfile.ZipFile(io.BytesIO(response.content)) as z:
            z.extractall(self.adb_dir)
        self.adb_executable = self._get_adb_path()
        if self.os_type != 'windows' and self.adb_executable:
            os.chmod(self.adb_executable, 0o755)
        print_success("ADB setup complete.")
    except Exception as e:
        print_error(f"Failed to download ADB: {e}")
ADB is downloaded to ./adb/platform-tools/ in the project directory and does not require system installation.

​
Verify Installation

To confirm successful installation, check for these indicators:
1

Application Launches

The main menu should display with all 7 options (PC) or 6 options (Termux).
2

Status Bar Visible

At the top of the screen, you should see:
  • Mode: ADB or Termux
  • ADB: Installed or N/A (Local)
  • Device: None (will update after scanning)
  • Key: None (will update after decryption)
3

Virtual Environment Active

Check that dependencies are isolated:
# Windows
where python
# Should show: .\venv\Scripts\python.exe

# Linux/macOS
which python
# Should show: ./venv/bin/python

​
Troubleshooting

Download Python from https://www.python.org/downloads/ and ensure “Add Python to PATH” is checked during installation.
Make the launcher executable:
chmod +x start.sh
bash start.sh
Manually download ADB platform tools from https://developer.android.com/tools/releases/platform-tools and extract to ./adb/platform-tools/.
Run termux-setup-storage manually and grant permissions when prompted. Restart Termux after granting permissions.
Delete the virtual environment and reinstall:
# Windows
rmdir /s venv
start.bat

# Linux/macOS
rm -rf venv
bash start.sh

​
Next Steps

Now that the tool is installed, proceed to the Quick Start guide:

Quick Start Tutorial

Learn how to perform your first backup extraction and decryption

Build docs developers (and LLMs) love

Get started for freeTalk to us