whatsapp-chat-exporter reads your own WhatsApp database, encrypted or not

A parser for databases you already have the keys to

The project is described as a customizable, cross-platform tool for parsing WhatsApp chat databases from Android and iOS or iPadOS backups, and the documentation says it was inspired by the Telegram Chat Export Tool. The output is the history of your conversations in HTML and JSON, and the tool supports the Android formats .crypt12, .crypt14 and .crypt15 as well as the latest database formats. The important framing is that this is a local parser, not a service. Nothing is uploaded, there is no account, and the input is a file you copied off your own phone or out of your own backup. The audience is someone who wants their history as a document rather than as an app, for an archive, for a legal matter, for research, or because they are about to delete the account. The packaging is plain PyPI, the package is whatsapp-chat-exporter, the console script is wtsexporter, and the licence is MIT with Python 3.10 and above required.

The plain Android database is the easiest case

The unencrypted path starts with extracting the WhatsApp database with whatever means you have, and the project links to its own WhatsApp-Key-DB-Extractor for the case where you have root or an otherwise readable device, with the note that the extractor only works on Android 4.0 to 13. The files you need in the working directory are the message database, which is called msgstore.db, the contact database, which is called wa.db, and a copy of the WhatsApp media directory taken directly from the phone. The contact database matters for more than names, because the exporter uses it to map your chats, and a chat with no matching contact is a chat with no title. Once the files are in place, the extraction is one command:

wtsexporter -a

The working directory itself is something you create, and the README suggests a directory named working_wts, and the tip for macOS users is to grant Full Disk Access to Terminal in the Security and Privacy settings before using the exporter, which is the kind of detail that only appears once someone has hit it.

Crypt12 and Crypt14 need the key file from the device

The older encrypted backups are handled with a key file rather than a password. The instructions are to install pycryptodome, or the android_backup extra that installs it along with the tool:

pip install pycryptodome
pip install whatsapp-chat-exporter["android_backup"]

The key file itself comes from the phone. If you have root access, you can find it at /data/data/com.whatsapp/files/key, and otherwise, if you used the key extractor before, it appears in the WhatsApp backup directory as WhatsApp/Databases/.nomedia. You place the key file, named key, and the encrypted backup, named msgstore.db.crypt14, in the working directory, along with wa.db and the media directory, and then run:

wtsexporter -a -k key -b msgstore.db.crypt14

The two flags are the key file and the backup file, and they are the whole interface. This is the part of the tool that is worth thinking about, because the key file is a decryption key stored on the device, and the same key that unlocks your backups is the one an attacker would want. The project handles it locally and the key never leaves the machine, but it is worth knowing what a file called .nomedia in a backup directory is.

Crypt15 is the easiest one, if you kept the hex key

The newest format is the end-to-end encrypted backup, and the README says crypt15 is now the easiest way to decrypt a backup. The reasoning is that WhatsApp shows you a 32 byte hex key when you enable an end-to-end encrypted backup, and if you have that key you can decrypt the backup directly. If you do not have it, you can still use the key file extracted the same way as for crypt12 and crypt14. Crypt15 also needs javaobj-py3, installable on its own or through the crypt15 extra:

pip install javaobj-py3
pip install whatsapp-chat-exporter["crypt15"]

You have to create the end-to-end encrypted backup first, with the instructions in WhatsApp's own help centre, and then copy the backup files to your computer, with the encrypted backup named msgstore.db.crypt15, the contact database named wa.db, and the WhatsApp media folder copied directly from the phone. With the key file present, the command is:

wtsexporter -a -k encrypted_backup.key -b msgstore.db.crypt15

and with the 64 hex digit key instead, the same key is passed to the -k option. The advice to take a copy of the database before you uninstall WhatsApp or delete your account, because you may want to run the exporter again on the same database in future as the exporter develops, is the kind of warning that only appears in a tool whose author has thought about the user's timeline.

Enriching contacts from a vCard when wa.db is empty

One failure mode is documented with a specific fix. The default WhatsApp contact database typically contains contact names extracted from the phone, and the exporter used those names to map the chats, but in some reported cases that database was never populated, which leaves you with a set of chats and no way to tell them apart. The remedy is to export your contacts to a vCard file from the phone, or from a cloud provider such as Google Contacts, install the vcards extra, and pass the file in:

pip install whatsapp-chat-exporter["vcards"]
wtsexporter -a --enrich-from-vcards contacts.vcf --default-country-code 852

The default country code flag exists because vCard phone numbers are not always in international format, and a number without a country prefix cannot be matched against a contact list. This is a small flag doing real work, and the fact that it is a first-class option rather than a hidden default is a sign of how the tool has been used in anger. On iOS and iPadOS the path is different, since you make an iPhone or iPad backup with iTunes or Finder first, with Apple's support links for the Mac, Windows and iPad cases given in the documentation.

The packaging, the sanitising, and a release called a security release

The dependencies are three and all three are visible in the output. jinja2 renders the HTML, bleach sanitises it, and tqdm draws the progress bar, and the optional extras are named after the formats they enable, with android_backup, crypt12, crypt14, crypt15, all, everything and backup all pulling in pycryptodome and javaobj-py3 in various combinations. The presence of bleach is worth pausing on, because the output contains other people's messages, and a chat history rendered as HTML with an unescaped message body is a script injection waiting to happen. The repository is classified as Development Status 4, Beta, is intended for end users on the desktop, and ships a SECURITY.md. The release history is where the project's own priorities show, with 0.13.0rc2 in January 2026, a 0.13.0 major release on 2026-01-24, and 0.13.1 titled Security Release dated 2026-10-12, published on 2026-10-11, before the last push on 2026-10-13. A project that names a release after security rather than after a feature is telling you that it treats that as part of the contract.

Where this tool stops

Three boundaries. The first is the obvious one. This parses backups you can already open, and the formats it decrypts are protected by keys that live on your device or are shown to you by the app, so the tool is a reader for your own data and not a way to reach anyone else's. The second is coverage. The key extractor linked for Android only works on Android 4.0 to 13, and every WhatsApp backup format is a moving target, since the app can change the database layout and the backup encryption without notice, and the crypt15 support is the newest of the three and therefore the least battle tested. The third is what you do with the output. The HTML is a faithful rendering of a conversation, which means it contains the personal data of everyone you talked to, and sanitising the markup does not decide what should be in the file, so an export that goes into a shared drive, an email or a dataset needs a decision about redaction that the tool does not make for you. The honest summary is that this is a well-built local parser with a clear licence and a security-minded release history, used on data you already control.

Editorial conclusion

whatsapp-chat-exporter is the right tool for archiving your own chat history, for a court case, a research dataset, or simply a record you want to keep before you delete an account, because it handles every backup format WhatsApp has shipped recently and it produces both a human-readable page and structured JSON. It is not a tool for reading someone else's messages, and the formats it decrypts are the ones your own device protects with keys it will only give to you. Before you run it, take the backup the project asks for, because the tool warns that the database may change under you as the exporter develops, and if you publish the output, remember that the HTML contains other people's messages, so the sanitising that bleach does is a floor and not a policy.

Frequently asked questions

Official sources

1. KnugiHK/WhatsApp-Chat-Exporter on GitHub
2. License: MIT
3. Project website
4. README
5. Releases