Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Library/CLI utility to parse, organize and export messages in Facebook archives

Project description

CLI tool/library to parse, organize and export your Facebook message archives.

Facebook data can be downloaded via the link at the bottom of your settings page:

This library makes use of the messages.htm file located in the html/ directory inside your archive.


Facebook exports your messages as one gigantic HTML file. Messages are grouped into individual threads, though chats with a single person are broken up throughout the file, which reads oldest-to-newest. That’s annoying. This fixes that.


To install via pip, just run:

$ pip install fbparser

To install locally, from the same directory as, run:

$ python install

Example use

To export your threads to CSV, from the directory containing messages.htm, run this command:

$ fbparser --csv messages.htm

This will create a directory named fbparser_out/ in your current directory containing your CSV exports. Exports can also be made in JSON or plaintext formats (with --json and `--text), or printed to the console with --stdout

To specify your Facebook name (to remove from filenames), use the --name flag. If you specify your Facebook UID with --uid, that UID will be replaced with the name you specified. For example:

$ fbparser --csv --name="John Smith" --uid="" messages.htm

Everywhere is found, it will be replaced with John Smith, which will also be removed from export filenames for clarity.

Replacing names/UIDs

Facebook’s archives are littered with UIDs and people that have changed their display names multiple times. To substitute certain names, feed in a file with --replace=file_name.txt


J Smith=John Smith Smith
John H Smith=John Smith

Each line should be formatted like Name to replace=New name

FBParser merges threads containing the same users, so if you see numerous threads for the same person with different display names (or UIDs), this will correct those names prior to merging the threads.


$ fbparser --csv --uid="" --name="John Smith" --replace="replace.txt" messages.htm

Parsing errors

If you encounter errors trying to parse an archive, use the --sanitize flag. This creates a backup as messages.htm.bak and writes the new version to the original filename before attempting to parse the file.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for fbparser, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size fbparser-1.0.0-py3-none-any.whl (12.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size (13.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page