Skip to main content

​
Overview

The WhatsApp Forensic Tool runs seamlessly on Windows with automatic dependency management. The start.bat launcher handles Python installation, virtual environment setup, ADB download, and dependency installation.

​
Prerequisites

​
System Requirements

  • Operating System: Windows 7 or later (Windows 10/11 recommended)
  • Python: 3.8 or higher (automatically installed if missing)
  • USB Drivers: Device-specific drivers for ADB connectivity
  • Storage: At least 500MB free space for tools and dependencies
  • Internet: Required for initial setup (downloading Python, ADB, packages)
The launcher script (start.bat) will automatically check for Python and guide you through installation if it’s not found.

​
Installation

​
Quick Start

1

Download the Tool

Clone or download the WhatsApp Forensic Tool 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 from Command Prompt:
start.bat
The launcher will automatically:
  • Check for Python installation
  • Create a virtual environment (venv)
  • Install all Python dependencies
  • Launch the application
3

Connect Your Device

  • Enable USB Debugging on your Android device
  • Connect via USB cable
  • Authorize the computer when prompted on your phone

​
What start.bat Does

The Windows launcher (start.bat) performs these operations: 
# 1. Check Python Installation
python --version >nul 2>&1
if %errorlevel% neq 0 (
    # Opens Python download page if not found
    start https://www.python.org/downloads/
)

# 2. Create Virtual Environment (if doesn't exist)
if not exist "venv" (
    python -m venv venv
)

# 3. Activate Virtual Environment
call venv\Scripts\activate

# 4. Install Dependencies
pip install -r requirements.txt

# 5. Launch Application
python main.py
The virtual environment keeps all dependencies isolated from your system Python installation, preventing conflicts.

​
Python Installation on Windows

If Python is not detected, the launcher will open the official Python download page.

​
Manual Installation Steps

1

Download Python

Visit python.org/downloads and download the latest Python 3.x installer for Windows.
2

Run Installer

IMPORTANT: Check the box “Add Python to PATH” during installation.This ensures python command is available system-wide.
3

Verify Installation

Open Command Prompt and verify:
python --version
pip --version
4

Re-run start.bat

After Python installation, double-click start.bat again.
If you forget to check “Add Python to PATH”, you’ll need to add it manually via System Environment Variables or reinstall Python.

​
ADB Setup

​
Automatic Download

The tool automatically downloads ADB platform tools on first run:
  • Source: Official Google Android SDK Platform Tools
  • Location: adb/platform-tools/ directory
  • Version: Latest stable release for Windows
The tool detects your OS and downloads the appropriate version from: 
https://dl.google.com/android/repository/platform-tools-latest-windows.zip

​
Manual ADB Installation (Optional)

If automatic download fails:
1

Download Platform Tools

Visit developer.android.com/studio/releases/platform-tools
2

Extract Files

Extract the ZIP file to the adb/ directory in the tool folder.
3

Verify ADB

Open Command Prompt in the adb/platform-tools/ directory:
adb.exe version

​
USB Driver Requirements

​
Installing Device Drivers

Windows requires specific USB drivers for ADB communication:
Install Google USB Driver:
  1. Download from developer.android.com/studio/run/win-usb
  2. Extract and run android_winusb.inf
  3. Or install via Windows Device Manager

​
Verifying Driver Installation

1

Connect Device

Connect phone via USB with USB Debugging enabled.
2

Check Device Manager

Open Windows Device Manager:
  • Look under “Android Device” or “Portable Devices”
  • Your device should appear without a yellow warning icon
3

Test ADB Connection

Run in Command Prompt:
cd adb\platform-tools
adb.exe devices
Expected output:
List of devices attached
ABC123XYZ    device
If you see “unauthorized” status, check your phone screen and authorize the computer.

​
Windows Defender & Antivirus

​
Potential Issues

Antivirus software may interfere with the tool:
  1. ADB Blocking: Some antivirus programs flag ADB as suspicious
  2. Python Script Blocking: Scripts downloading files may be blocked
  3. File Access: Real-time scanning may slow down backup extraction
1

Add Exclusions

Add these folders to Windows Defender exclusions:
  • Tool installation folder (entire directory)
  • adb/ subdirectory
  • venv/ Python virtual environment
Windows Defender Settings:
  1. Open Windows Security
  2. Virus & threat protection → Manage settings
  3. Exclusions → Add or remove exclusions
  4. Add folder → Select tool directory
2

Temporarily Disable (If Needed)

If issues persist during installation:
  • Temporarily disable real-time protection
  • Run start.bat
  • Re-enable protection after setup
Only disable antivirus temporarily and only if you trust the tool source.

​
Running the Tool

​
First Run

On first execution: 
cd C:\path\to\whatsapp-forensic-tool
start.bat
You’ll see: 
===========================================
  WhatsApp Backup Forensic Tool Launcher
===========================================
[*] Creating virtual environment...
[*] Activating virtual environment...
[*] Checking dependencies...
[*] Starting Application...

​
Subsequent Runs

After initial setup, the launcher:
  • Skips virtual environment creation (already exists)
  • Activates existing venv
  • Updates dependencies if requirements.txt changed
  • Launches immediately

​
Common Windows Issues

​
Issue: “Python is not recognized”

Cause: Python not in system PATH Solution:
1

Verify Installation

Check if Python is installed:
where python
2

Add to PATH Manually

  1. Search “Environment Variables” in Windows Start Menu
  2. Edit “Path” variable under System Variables
  3. Add Python installation paths:
    • C:\Users\YourName\AppData\Local\Programs\Python\Python311
    • C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts
3

Restart Command Prompt

Close and reopen Command Prompt to reload PATH.

​
Issue: “ADB device not found”

Possible Causes:
  • USB Debugging not enabled
  • Missing USB drivers
  • Wrong USB cable (charge-only vs data cable)
  • USB port issue
Solutions:
1

Enable USB Debugging

On your Android device:
  1. Settings → About Phone → Tap “Build Number” 7 times
  2. Settings → Developer Options → Enable “USB Debugging”
2

Try Different USB Port

  • Use USB 2.0 ports (not 3.0/3.1)
  • Avoid USB hubs
  • Try rear ports on desktop PCs
3

Restart ADB Server

cd adb\platform-tools
adb.exe kill-server
adb.exe start-server
adb.exe devices
4

Check USB Cable

Use a data-capable USB cable (not charge-only).

​
Issue: “Permission denied” errors

Cause: Windows User Account Control (UAC) restrictions Solution:
  • Run Command Prompt as Administrator
  • Right-click start.bat → “Run as administrator”
  • Ensure you have write permissions in the tool directory

​
Issue: Virtual environment activation fails

Error: venv\Scripts\activate.bat not found Solution: 
# Delete corrupted venv
rmdir /s /q venv

# Re-run launcher to recreate
start.bat

​
Issue: Slow performance during media extraction

Cause: Windows Defender real-time scanning Solution:
  • Add backups/ folder to Windows Defender exclusions
  • Use SSD for storage (faster than HDD)
  • Close other disk-intensive applications

​
Issue: “Access denied” when accessing backups folder

Cause: Folder permissions or antivirus lock Solution:
1

Check Folder Permissions

Right-click backups folder → Properties → Security → Ensure your user has Full Control
2

Unlock Files

If files are locked by antivirus:
  • Temporarily disable real-time protection
  • Or add exclusion for backups/ folder

​
Advanced Configuration

​
Running Without start.bat

For advanced users: 
# Activate virtual environment manually
call venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run with custom Python interpreter
python main.py

# Or use venv Python directly
venv\Scripts\python.exe main.py

​
Troubleshooting Path Issues

If encountering path-related errors: 
# Set working directory explicitly
cd /d %~dp0

# Run from correct location
python main.py

​
Firewall Configuration

If using ADB over WiFi (advanced):
  • Allow ADB through Windows Firewall
  • Open port 5555 for TCP connections

​
Performance Tips

Use SSD Storage

Store backups on SSD for faster extraction and decryption.

Disable Real-Time Scanning

Exclude tool directories from antivirus during operations.

Close Background Apps

Free up RAM and CPU for faster processing.

Use USB 2.0 Ports

Sometimes more stable than USB 3.0 for ADB.

​
Next Steps

Quick Start Guide

Learn the basic workflow and features

Troubleshooting

Common issues and solutions

Deploy to Termux

Run the tool directly on your Android device

API Reference

Technical documentation for developers

Build docs developers (and LLMs) love

Get started for freeTalk to us