imessage-wrapped 0.1.9

Export and analyze iMessage conversations from macOS SQLite database

iMessage Wrapped

Export and analyze your iMessage conversations from the macOS SQLite database.

Quick Start

🖥️ Desktop App (No Terminal Required!)

Download for macOS

1. Download and open iMessage-Wrapped.dmg
2. Drag to Applications folder
3. Launch the app
4. Click "Analyze My Messages"
5. Your wrapped opens in browser automatically

See desktop/ for building from source.

💻 Command Line

pip install imessage-wrapped
imexport analyze

That's it! By default, the command will:

1. 🔄 Auto-export your messages (if not already exported)
2. 📊 Analyze your messaging patterns
3. ☁️ Upload anonymized statistics
4. 🔗 Give you a shareable URL like: https://imessage-wrapped.fly.dev/2025/abc123xyz

Want to see full details in the terminal instead? Use imexport analyze --no-share

Features

✅ Dashboard - Interactive visualizations of your messaging patterns
✅ Easy Sharing - One command to upload and get a shareable link
✅ Secure - HTTPS, encrypted database
✅ Deploy Anywhere - Fly.io ready (free tier available)

🔒 Data Privacy

Your message content NEVER leaves your computer.

By default, we only upload aggregated statistics to create your shareable link. Here's exactly what is and isn't uploaded:

✅ What IS Uploaded (Statistics Only)

• Counts: Total messages sent/received, tapbacks given/received, attachments, etc.
• Averages: Message length, response times, punctuation usage
• Distributions: Hour of day, day of week, month patterns
• Emojis: Which emojis you used and how often
• Dates: Your busiest messaging days, streak lengths
• Anonymized Identifiers: Contact identifiers are SHA256-hashed (e.g., phone_a3b2c1d4e5f6)

❌ What is NOT Uploaded (Stays Private)

• Message Text: No actual message content is ever sent
• Contact Names: All names are stripped out before upload
• Phone Numbers/Emails: Original identifiers are one-way hashed
• Conversation Content: No snippets, samples, or quotes
• Attachments: No photos, videos, or file content
• Personal Info: Nothing that could identify you or your contacts

Usage

As a Library

from imessage_wrapped import MessageService, Exporter

service = MessageService()
data = service.export_year(2025)

exporter = Exporter()
exporter.export_to_file(data, "messages_2025.json")

See example_usage.py for a complete working example.

As a CLI

After installation, use the imexport command:

# Export current year (default)
imexport export

# Export specific year
imexport export --year 2024

# Custom output path
imexport export --output my_messages.json

# Custom database path (for testing)
imexport export --database /path/to/test/chat.db

# Compact JSON (no indentation)
imexport export --indent 0

# Analyze and share (default behavior)
imexport analyze

# Analyze with full terminal output (no sharing)
imexport analyze --no-share

# Show help
imexport --help

Alternatively, run without installation:

python -m imessage_wrapped export --year 2024

CLI Commands:

• imexport export: Export iMessage conversations to JSON
• imexport analyze: Analyze and share your wrapped (auto-exports if needed, use --no-share for full terminal output)

Requirements

• Python 3.10+
• macOS with Full Disk Access permission
• rich library for terminal output

Installation

From PyPI

pip install imessage-wrapped
imexport

From Source (Development)

git clone https://github.com/gtarpenning/imessage-wrapped.git
cd imessage-wrapped
pip install -e .

macOS Permissions

Requires Full Disk Access to read the iMessage database:

1. Open System Settings
2. Go to Privacy & Security → Full Disk Access
3. Add Terminal (for CLI) or the Desktop App
4. Restart the application

Deployment

See RELEASE-GUIDE.md for deploying the CLI, Desktop App, or Web App.