Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

iMessage Conversation Analyzer

Copyright 2020-2021 Caleb Evans
Released under the MIT license

This macOS CLI program will read the contents of an iMessage conversation via the Messages app's database on your Mac. You can then gather various metrics of interest on the messages and attachments collected.

Much of this program was inspired by and built using findings from this blog post by Yorgos Askalidis.


Please note that currently, you can only query conversations between you and a single other person (i.e. group chats are currently unsupported).


1. Install Python 3

macOS does not include Python 3 out of the box, but you can install Python 3 with the Homebrew package manager.

brew install python@3

2. Set up virtualenv

pip3 install virtualenv
virtualenv --python=python3 .virtualenv
source .virtualenv/bin/activate

3. Install project depdendencies

pip install -r requirements.txt


-c / --contact-name

Required; the combined first and last name of the macOS contact whose conversation you want to fetch (e.g. John Doe).

ica -c 'John Doe' -m ica/metrics/

-m / --metric-file

Required; a Python file with an analyze() function; this file must return a pandas DataFrame. See the examples in ica/metrics.

ica -c 'John Doe' -m ica/metrics/

-f / --format

Optional; the output format of the result. Omit this argument for a simple textual table, or specify csv to print output as CSV.

ica -c 'John Doe' -m ica/metrics/ -f csv

You can also output as CSV and use the pbcopy command for easy copy/pasting into a spreadsheet program (like Excel or Numbers).

ica -c 'John Doe' -m ica/metrics/ -f csv | pbcopy


Gathers metrics of your choice for the entire history of a macOS Messages conversation