Mastodon Export to Static HTML Archive: Self-Hosting Backup

You want to create a permanent, self-hosted backup of your Mastodon posts that works even if your instance goes offline. Mastodon offers a built-in export tool that produces CSV and JSON files, but these formats require specialized software to read. A static HTML archive converts your public posts into a browsable website that you can host on any basic web server or even your local computer. This article explains how to generate that archive using the Mastodon API and open-source tools, and how to host the result without needing a database or server-side scripts.

How Mastodon Export and Static HTML Archiving Works

Mastodon provides an export feature that packages your account data into a single ZIP file. This file contains separate JSON files for your statuses, media attachments, bookmarks, lists, and followers. The JSON format is machine-readable but not human-friendly for browsing. A static HTML archive tool reads these JSON files and generates a folder of HTML pages, CSS stylesheets, and JavaScript that recreates your timeline as a navigable website.

The archiving process does not require any server-side components. The output is a set of static files that any web server can serve. This means your backup remains accessible even if the original Mastodon instance shuts down. The archive includes only your public and unlisted posts. Direct messages and private posts are not included in the default export for privacy reasons.

Prerequisites Before You Start

You need the following items before generating the archive:

• A Mastodon account with access to the Preferences > Export page.
• Python 3.8 or later installed on your computer to run the conversion tool.
• A web hosting destination such as GitHub Pages, Netlify, or a basic web server folder.
• At least 500 MB of free disk space for the export and generated archive if you have many posts and media files.

Steps to Export Your Mastodon Data and Build a Static HTML Archive

Follow these steps in order to create your self-hosted backup.

1. Request your Mastodon data export
   Log in to your Mastodon instance. Go to Preferences > Export. Click the button labeled “Request your archive.” The instance will generate a ZIP file containing all your export data. This process can take several minutes depending on the size of your account. You will receive a notification when the file is ready for download.
2. Download the ZIP archive
   Return to Preferences > Export after receiving the notification. Click the download link next to “Your archive is ready.” Save the ZIP file to a folder on your computer. Do not rename the file because the conversion tool expects the default filename structure.
3. Install the mastodon-archive Python tool
   Open a terminal or command prompt. Run the command: pip install mastodon-archive. This installs the tool and all its dependencies. If you use Python virtual environments, activate the environment before running the install command.
4. Extract the downloaded ZIP file
   Use your operating system’s archive utility to extract the ZIP file into a dedicated folder. For example, extract it to C:\mastodon-backup\export on Windows or ~/mastodon-backup/export on macOS or Linux. The extraction creates a folder structure containing outbox.json, likes.json, media_attachments, and other files.
5. Run the mastodon-archive tool to generate HTML
   In the terminal, navigate to the folder containing the extracted export. Run the command: mastodon-archive generate --input outbox.json --output ./archive. Replace ./archive with your desired output folder path. The tool reads the JSON data and creates a static website inside the specified output folder.
6. Verify the generated archive
   Open the output folder and double-click the index.html file. Your browser should display your timeline with individual post pages. Check that media attachments such as images and videos appear correctly. If media is missing, ensure the media_attachments folder from the export is in the same directory as outbox.json when you ran the tool.
7. Upload the archive to your web host
   Copy the entire output folder to your web hosting destination. For GitHub Pages, create a new repository, upload the folder contents, and enable Pages in the repository settings. For Netlify, drag and drop the folder onto the Netlify dashboard. For a basic web server, copy the folder to the server’s public HTML directory.

Common Issues and Limitations When Self-Hosting a Mastodon Archive

Media attachments are missing from the generated HTML

The mastodon-archive tool embeds media by linking to the local media_attachments folder. If you extracted the ZIP into a separate location from the outbox.json file, the tool cannot find the media. Place the media_attachments folder in the same directory as outbox.json before running the generate command. Alternatively, use the --media-dir flag to specify the exact path to the media folder.

Archive does not include replies or mentions from other users

The Mastodon export includes only your own posts. Replies from other users to your posts are not included because they belong to the other user’s account. The archive shows your posts in chronological order but does not display the full conversation threads. This is a limitation of the export data, not the archiving tool.

Large archives fail to generate or take too long

If you have thousands of posts, the Python tool may run out of memory. Reduce the memory usage by generating the archive on a machine with at least 4 GB of RAM. Alternatively, use the --limit flag to restrict the number of posts included. For example, --limit 500 generates an archive of the 500 most recent posts.

Archive does not display correctly on mobile devices

The default mastodon-archive output includes responsive CSS, but older versions of the tool may produce layouts that do not adapt to small screens. Update the tool to the latest version by running pip install --upgrade mastodon-archive. If the issue persists, add a custom CSS file to the archive’s static folder with mobile-friendly styles.

Mastodon Export Formats: JSON vs Static HTML Archive

Item	JSON Export	Static HTML Archive
File format	JSON (machine-readable)	HTML, CSS, JavaScript (human-readable)
Viewing requirement	Text editor or script	Any web browser
Media embedding	Separate media_attachments folder	Inline images and video players
Search functionality	Requires grep or custom script	Browser find (Ctrl+F) works on each page
Hosting complexity	N/A (not designed for hosting)	Upload folder to any static web host
Privacy	Includes only public and unlisted posts	Same limitation as JSON export

The static HTML archive is the better choice for long-term personal backup because it remains readable without any specialized software. The JSON export is better suited for data analysis or migration to another service.

You can now create a self-hosted static HTML backup of your Mastodon posts using the export feature and the mastodon-archive Python tool. The generated website preserves your timeline in a format that any web server can host. For ongoing backups, set a reminder to request a new export every month and regenerate the archive. To extend the archive, add a search page by including a client-side search library such as Lunr.js in the static folder.