You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit dde630e
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+3-4Lines changed: 3 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -72,16 +72,15 @@ After a successful run, the archive will be organized as follows:
72
72
73
73
The script runs on **Linux, macOS, and Windows** (Python 3.10+).
74
74
75
-
> ⚠️ **Run the script on the same machine where the media files are physically stored.** Processing files over a network share (NFS, SMB, etc.) will be significantly slower.
75
+
> ⚠️ If you have WhatsApp on Android, **run the script on the same machine where the media files are physically stored.** Processing files over a network share (NFS, SMB, etc.) will be significantly slower.
76
76
77
77
---
78
78
79
79
## Prerequisites
80
80
81
81
-**Python 3.10+** required
82
-
-**Android**: End-to-end encrypted backup must be **enabled** in WhatsApp before pulling the database
82
+
-**Android**: End-to-end encrypted backup must be **enabled** in WhatsApp before pulling the database. Root is not required
83
83
-**iOS/iPadOS**: End-to-end encrypted backup must be **disabled**
84
-
-**ADB** required for automatic retrieval (`--mode adb`)
85
84
86
85
See [docs/prerequisites.md](docs/prerequisites.md) for full setup instructions: E2E backup configuration, database extraction (Android and iOS), contacts pull, and locating your media folder.
Enable it and note the **cryptographic key** — a long alphanumeric string.
38
40
**Store it somewhere safe**; you will need it every time you pull a fresh backup. If you lose this key, you will lose access to all your backups.
39
41
42
+
When asked, create the end-to-end ecrypted backup.
43
+
40
44
> If this step is skipped, the `.crypt15` backup file cannot be decrypted and the script will not work on a non-rooted device.
41
45
42
46
**iOS / iPadOS users** — End-to-end encrypted backup must be **disabled**. If it is enabled, the database inside the iPhone backup is encrypted in a way that cannot be read by this script. Disable it in WhatsApp before creating your device backup.
@@ -45,11 +49,30 @@ Enable it and note the **cryptographic key** — a long alphanumeric string.
45
49
46
50
## 3. Android Setup
47
51
52
+
53
+
### Your WhatsApp Media Folder
54
+
55
+
Before you run the script, you need your WhatsApp (Media) folder on disk - actually, the folder called `WhatsApp` that **contains** the `Media` subfolder.
56
+
You need to copy this folder from your phone: you can use [Syncthing](https://syncthing.net/) to ease the process.
57
+
58
+
```
59
+
/path/to/WhatsApp/
60
+
├── Databases/
61
+
└── Media/
62
+
├── WhatsApp Images/
63
+
├── WhatsApp Video/
64
+
└── WhatsApp Audio/
65
+
```
66
+
67
+
Pass the path to the `WhatsApp/` folder (not `Media/`) to the script via `--wa_root`.
68
+
69
+
> ⚠️ **Run the script on the same machine where the media files are physically stored.** Processing files over a network share (NFS, SMB, etc.) will be significantly slower — the script hashes and copies every file in the archive. Running locally is strongly recommended.
The simplest approach for most users. Connect your phone via USB with USB Debugging enabled, then let the script handle the pull and decryption automatically.
75
+
This is the simplest approach for most users. Connect your phone via USB with USB Debugging enabled, then let the script handle the pull and decryption automatically.
53
76
54
77
> 💡 **ADB required.** Install it before running `--mode adb`:
@@ -62,13 +85,15 @@ Run the script with `--mode adb`:
62
85
python3 wa_media_archiver.py \
63
86
--mode adb \
64
87
--e2e your_cryptographic_key \
65
-
--wa_root /path/to/WhatsApp \
88
+
--wa_root /path/to/WhatsApp/storage \
66
89
--output /path/to/output
67
90
```
68
91
> 💡 On Windows, replace `\` with `` ` `` (PowerShell) or `^` (cmd.exe).
69
92
70
93
The script pulls the encrypted backup and contacts directly from the device and decrypts on the fly. No separate steps needed.
71
94
95
+
> Please note that this is just a simple example: you can add many options to customize the run, please see [docs/running-the-script.md](docs/running-the-script.md).
96
+
72
97
---
73
98
74
99
#### Alternative — Manual Pull
@@ -115,7 +140,7 @@ Alternatively, skip the manual decrypt and let the script handle it by passing t
115
140
python3 wa_media_archiver.py \
116
141
--msgstore /path/to/msgstore.db.crypt15 \
117
142
--e2e your_cryptographic_key \
118
-
--wa_root /path/to/WhatsApp \
143
+
--wa_root /path/to/WhatsApp/storage \
119
144
--output /path/to/output
120
145
```
121
146
@@ -140,25 +165,6 @@ Pass the file to the script with `--contacts`.
140
165
141
166
> 💡 You only need to repeat this if your contacts have changed significantly since the last run.
142
167
143
-
---
144
-
145
-
### Your WhatsApp Media Folder
146
-
147
-
The script needs a copy of your WhatsApp (Media) folder on disk - actually, the folder that **contains** the `Media/` subfolder.
148
-
You need to copy this folder from your phone: you can use [Syncthing](https://syncthing.net/) to ease the process.
149
-
150
-
```
151
-
/path/to/WhatsApp/
152
-
├── Databases/
153
-
└── Media/
154
-
├── WhatsApp Images/
155
-
├── WhatsApp Video/
156
-
└── WhatsApp Audio/
157
-
```
158
-
159
-
Pass the path to the `WhatsApp/` folder (not `Media/`) to the script via `--wa_root`.
160
-
161
-
> ⚠️ **Run the script on the same machine where the media files are physically stored.** Processing files over a network share (NFS, SMB, etc.) will be significantly slower — the script hashes and copies every file in the archive. Running locally is strongly recommended.
|`-msg` / `--msgstore`| No | Path to `msgstore.db`, `msgstore.db.crypt15`, or `ChatStorage.sqlite`. Not needed with `--ios_backup`. Defaults to `msgstore.db` in the current folder |
27
27
|`-e2e` / `--e2e_key`| If encrypted | Your cryptographic key for `.crypt15` decryption |
28
28
|`-c` / `--contacts`| No | Path to the `wa_contacts` file exported via ADB (Android only) |
29
-
|`-wa` / `--wa_root`| Android / iOS pre-extracted | Root path of your WhatsApp folder. Android: folder containing `Media/`. iOS pre-extracted: `AppDomainGroup-group.net.whatsapp.WhatsApp.shared` folder. Not required with `--ios_backup` or `--mode restore`|
29
+
|`-wa` / `--wa_root`| Android / iOS pre-extracted | Root path of your WhatsApp folder from mass storage. Android: this contains the `Media/` folder. iOS pre-extracted: `AppDomainGroup-group.net.whatsapp.WhatsApp.shared` folder. Not required with `--ios_backup` or `--mode restore`|
30
30
|`--ios_backup`| iOS (recommended) | Path to the iPhone backup directory (the folder containing `Manifest.db`). Mutually exclusive with `--wa_root`|
31
31
|`--ios_password`| No | Password for an encrypted iPhone backup. Only needed when the backup is encrypted |
32
32
|`--ios_contacts`| No | Path to `ContactsV2.sqlite` for iOS contacts. Auto-extracted from `--ios_backup` if omitted |
@@ -62,7 +62,7 @@ The examples below use `\` to split long commands across multiple lines. Replace
0 commit comments