Frequently Asked Questions
May 30, 2026 · View on GitHub
I cannot connect to the messages database. What do I do?
Ensure your terminal emulator has full disk access if using the default location or ensure that the path to the database file is correct. You can enable this in System Settings > Privacy & Security > Full Disk Access.
Are emojis, tapbacks (reactions), and other special message features preserved in the export?
Yes, all iMessage features are supported. See here for more detail.
Can it export messages from third-party apps that integrate with iMessage?
Yes. See here for more detail on supported features.
Does imessage-exporter export message conversations that are in iCloud or on a user's iPhone/iPad but not on the user's Mac?
imessage-exporter only reads data present in the provided source, which can be a macOS chat.db, a local iOS backup (encrypted or unencrypted), or a jailbroken iOS sms.db. It cannot read data that is only stored in iCloud.
Can I force iCloud to download attachments that were offloaded?
In the Messages app, if you click the info (ⓘ) button for a conversation and scroll to the bottom, there is a button that downloads all of the attachments for that conversation. This works on both macOS and iOS.
Can it export group conversations as well as individual chats?
Yes.
Can I export only specific conversations?
Yes, the --conversation-filter (-t) argument filters by contact name, phone number, or email. Multiple filters can be comma-separated, e.g., -t "steve@apple.com,5558675309". Substring matching is supported, so -t "+1555" matches all numbers with that prefix. All conversations containing the matched participants are included.
See here for details on imessage-exporter arguments.
How does the exporter handle previously exported messages?
If files with the current output type exist in the output directory, imessage-exporter will alert the user and the export will not start. If the export directory is clear, imessage-exporter will export all messages by default. Alternatively, it will export messages between the dates specified by the --start-date and --end-date arguments.
See here for details on imessage-exporter arguments.
Is it possible to export a conversation and re-integrate it back onto another Apple ID?
No, I do not want to be trusted with write access to your iMessage data. This software is read only.
Is there a search function?
No, this software just builds exports. I use ripgrep to search though the exported files.
Can it export messages between a specific date range?
Yes, the --start-date and --end-date arguments specify date ranges for exports.
See here for details on imessage-exporter arguments.
Are voice messages saved?
Expired ones cannot be because they are deleted from disk by the system. If you kept them, they are included in the exports.
Are messages deleted from the messages app erased from the database?
This software can recover some, but not all, deleted messages.
Messages removed by deleting an entire conversation or by deleting a single message from a conversation are moved to a separate collection for up to 30 days. Messages present in this collection are restored to the conversations they belong to. Apple details this process here.
Messages that have expired from this restoration process are permanently deleted and cannot be recovered.
In some instances, deleted messages are removed from the chat_message_join table but not from the messages table. These messages will populate in orphaned.html or orphaned.txt.
What is the orphaned file in my export?
Messages that cannot be associated with any conversation are written to orphaned.html or orphaned.txt. This can happen when a message's chat has been deleted from the chat_message_join table, or when the database has inconsistencies. These messages are preserved so no data is lost.
What export formats are supported? Can I export to PDF?
imessage-exporter supports txt and html export formats. There is no native PDF export, but you can export as HTML and then print to PDF from Safari. Use the --no-lazy flag when exporting for PDF, as it disables lazy-loading of images which is required for the print-to-PDF workflow to include all images.
How do I customize the appearance of HTML exports?
Each HTML export file links to an external style.css in the export directory. You can create this file to override the default styles. Since custom styles load after the embedded defaults, they take precedence at the same specificity.
What does --copy-method do and which should I choose?
disabled(default): Attachments are not copied; the export references them in-place by filesystem pathclone: Copies all attachment files as-is, preserving original formats and qualitybasic: Copies all files, convertingHEICimages toJPEGfor broader compatibilityfull: Copies all files, convertingHEICtoJPEG,CAF/AMRaudio toMP4,MOVvideo toMP4, and animated stickerHEICStoGIF
basic and full require external tools (sips or ImageMagick for images, afconvert or ffmpeg for audio, ffmpeg for video). The --diagnostics output shows which converters are detected on your system.
What does the --diagnostics flag show?
Diagnostics mode prints a summary of the database without exporting anything:
- Handle data: total handles, duplicated handles
- Message data: total messages, orphaned messages, messages in multiple chats, recoverable deleted messages, and the date range of all messages
- Attachment data: total attachments, referenced vs. on-disk data sizes, and missing file counts
- Thread data: total chats, duplicated chats, chats with no handles
- Global data: database file size, percentage of handles with resolved contact names, and detected media converters
What does --attachment-root do?
This option overrides where the app looks for attachment files. It is useful when attachment data is stored separately from the database, such as on an external drive. The provided path replaces the default ~/Library/Messages root and affects both the Attachments and StickerCache directories. It also works with jailbroken iOS sms.db databases (use --platform macOS). This option has no effect on iOS backups.
Why do I see "Unable to build contacts index"?
This warning means the Contacts database could not be read. The export will continue, but participants will be labeled with phone numbers and email addresses instead of resolved contact names. This commonly happens due to missing Full Disk Access permissions, since the contacts database is also protected. You can also specify a custom contacts database path with --contacts-path.
How fast is imessage-exporter?
This is a complicated question that depends on CPU, database size, chosen export type, encryption state, and chosen attachment handling style.
On my M1 Max MacBook Pro, approximate performance is as follows:
--copy-method | Messages exported per second |
|---|---|
disabled | > 145,000 |
clone | ≈ 42,000 |
basic | ≈ 350 |
full | ≈ 250 |
For more information on --copy-method, see here and here.
However, if you recently deleted a large amount of data from Messages, the database will be slow for awhile, resulting in significantly reduced performance from imessage-exporter.