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?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Ditchbook: Facebook to Micropub Toolkit

Ditchbook is a toolkit for taking a high-fidelity Facebook JSON export, and migrating selected content to your Micropub compatible website, including websites. Its a great way to own your own data, and free yourself from Facebook.



First, you'll need to clone or download this project. Ditchbook requires Python 3.6 or greater to run. I recommend installing inside of a virtualenv:

$ git clone
$ cd ditchbook
$ virtualenv -p python3.6 venv
$ . venv/bin/activate
$ python develop

Create a Facebook JSON Export

Once you've got a working installation, you'll need to create a Facebook export here. Select JSON for the type of export and use high resolution photos. This can take a few hours. Once you're done, download the ZIP file, and uncompress it into a directory. Let's assume you've placed it in a directory called "export" contained within your ditchbook directory.

Ingest and Convert Facebook Data

Next, you'll want to run the ingest script, which will try and read in data from your Facebook data, and then output it as standard microformats2 JSON data.

$ bin/ingest export

If all went well, you'll have a directory named mf2 containing your converted data. Huzzah!

Configure Micropub

Next, copy to and make the appropriate edits. You'll need to provide your micropub endpoint, micropub media endpoint, micropub token, and the destination.

In addition, you can configure a mapping of names to hyperlinks for when you've got "mentions" of people in your content.

Publish: Albums

Now, its time to publish your photo albums.

$ bin/publish-albums

Script will loop through the albums contained in your export, give you some basic information about each one, and give you the choice of migrating an album to your website, or not.

I'd recommend against uploading albums with many hundreds (or thousands) of photos. Facebook creates an album called "Mobile Uploads" that tends to contain every single photo ever uploaded with your iOS or Android device, and you're better off not migrating that album. The photos themselves will be migrated as "posts" in a future step, if you choose.

Publish: Posts

Finally, you can publish other "posts" from Facebook, which includes notes, status updates, and photos. Because the content isn't particularly well-suited for migration, ditchbook will ignore many types of content, and focuses on the types of data you'd like on your website. That means link sharing, events, and other related data won't be migrated.

At this time, ditchbook doesn't support migrating videos. Maybe I'll get around to it in the future. We'll see.

$ bin/publish-posts

This script will run in a similar fashion to the publish-albums script, but will automatically publish posts that have at least one photo. Everything else will ask you for confirmation.


Ideally, I'd like to make this process easier and more seamless for end users. Feel free to use the code to do that! I have no intention of using this code for any commercial purpose, and instead and primarily motivated to help people free themselves from Facebook, and control their own information.



Move your Facebook data over to your own website using Micropub







No releases published


No packages published