Requirements

  • macOS 12 Monterey or later (the iMessage database format changed in macOS 12).
  • Homebrew installed — if you do not have it, run the one-line installer at brew.sh.
  • The iMessage account signed in on this Mac must be the same account you want to export from.

Step 1: Grant Full Disk Access to Terminal

The iMessage database is stored in a protected location. Terminal needs explicit permission to read it.

1
Open System Settings (macOS 13+) or System Preferences (macOS 12).
2
Navigate to Privacy & Security → Full Disk Access.
3
Click the + button and add Terminal (found in /Applications/Utilities/Terminal.app). If Terminal is already in the list, make sure its toggle is enabled.
If you use iTerm2 or another terminal app, add that instead of Terminal. The permission follows the app, not the command.

Step 2: Install imessage-exporter

Open Terminal and run:

brew install imessage-exporter

This installs the open-source imessage-exporter command-line tool. It reads directly from your local iMessage database — nothing is sent to any server.

Step 3: Export Your Messages

Run the following command to export all conversations in plain text format with media files copied alongside:

imessage-exporter -f txt -c copy -o ~/imessage-export

Flag meanings:

  • -f txt — plain text format (required for XMOX)
  • -c copy — copies media files (voice notes, images) into the export folder
  • -o ~/imessage-export — output directory (you can change this path)
A full export of a large iMessage library can take several minutes and produce a large folder. If you only need one conversation, export just that contact (see tip below).

Step 4: Find the Right Conversation Folder

After the export, open ~/imessage-export in Finder. You will see one folder per contact or group, named by phone number or Apple ID:

~/imessage-export/
  +15551234567/
    +15551234567.txt
    attachments/
      audio_message.caf
  group_chat_abc123/
    ...

Locate the folder for the contact or group you want to analyse.

Step 5: ZIP the Conversation Folder

1
In Finder, right-click the contact's folder (e.g. +15551234567) and choose Compress.
2
A .zip file is created in the same location. This is what you upload to XMOX.

Step 6: Upload to XMOX

3
In your XMOX workspace, click + New Job and choose "iMessage Export".
4
Upload the ZIP file. XMOX parses the .txt conversation file and locates voice note attachments inside the attachments/ folder.
5
Processing completes when the job shows Ready. Voice notes (in Apple's .caf format) are converted to MP3 and transcribed automatically.

Tips for Large Libraries

  • To export only a specific contact: imessage-exporter -f txt -c copy -o ~/imessage-export -t "+15551234567"
  • The -t flag filters by phone number or email — this keeps the export small and fast.
  • Group chats use an internal ID, not a phone number. Run a full export first, then locate the group folder by recognising the contact names in the .txt file.
iMessage conversations are stored only on devices that have the account signed in with iMessage enabled. If you have not used iMessage on this Mac recently, some older messages may not be present locally.

Ready to analyse your iMessage conversations? Upload your export to XMOX now.

Open Workspace →