whatstk

Parse, analyze, and visualize WhatsApp chats with Python

Documentation • Try Live Demo • Tutorial

</div>

Features

📱 Parse WhatsApp exports from Android and iOS (including zip files)
🐼 Convert to pandas DataFrames for easy analysis
📊 Interactive visualizations powered by Plotly
🔧 Command-line tools for quick CSV conversions
🌍 Multi-language support for various WhatsApp date formats
🚀 Fast and efficient processing of large chat histories

Installation

pip install whatstk

Requirements: Python 3.11+

<details> <summary>Install development version</summary>

pip install git+https://github.com/lucasrodes/whatstk.git@develop

</details>

Quick Start

Export your WhatsApp chat

Follow the export instructions for your device.

Load and analyze

from whatstk import df_from_whatsapp

# Load chat into a DataFrame
df = df_from_whatsapp("path/to/chat.txt")

# Or directly from iOS zip export
df = df_from_whatsapp("path/to/chat.zip")

# Now use pandas to analyze
print(df.head())

Convert to CSV

whatstk-to-csv input_chat.txt output.csv

Visualize

from whatstk.graph import plot_user_message_count

# Interactive message count chart
fig = plot_user_message_count(df)
fig.show()

Documentation

Full documentation available at whatstk.readthedocs.io

Contributing

We welcome contributions! See our contribution guide to get started.

License

This project is licensed under the GPL-3.0 License.

Citation

If you use whatstk in your research or project, please cite:

@software{whatstk,
  author = {Rodés-Guirao, Lucas},
  title = {whatstk: WhatsApp analysis and parsing toolkit},
  url = {https://github.com/lucasrodes/whatstk},
  year = {2025}
}

or as

Lucas Rodés-Guirao. "whatstk, WhatsApp analysis and parsing toolkit", https://github.com/lucasrodes/whatstk

Featured Projects

[!NOTE] If you have created a project using whatstk, I'd love to know that and add it this list! Thanks a lot!

⭐ Star this repo if you find it useful!

Made with ❤️ by Lucas Rodés-Guirao

</div>

Whatstk

Install / Use

README