How to Restore a Mastodon Export Archive on a New Instance

When you leave a Mastodon instance, you can download an archive of your data including posts, media, and lists. However, simply uploading that archive to a new instance does not automatically load your old content into the active timeline. Mastodon’s archive is designed for data portability and backup, not as a live import tool that merges posts into the new account. This article explains what the export archive actually contains, how to restore it using the built-in import features, and what limitations you will encounter after the restore.

What the Mastodon Export Archive Contains and Its Limitations

When you request a data export from Mastodon under Preferences > Import and export > Data export, the server generates a ZIP archive. Inside, you will find several CSV files and an HTML file named “outbox.html” that contains all your public posts in a human-readable format. The CSV files include lists for accounts you follow, accounts that follow you, blocked accounts, muted accounts, and domain blocks. A separate folder named “media_attachments” holds the images and videos you uploaded to your posts.

The critical limitation is that the outbox.html file is not an importable format. Mastodon’s import system only processes CSV files. This means your old toots, boosts, and replies remain in the archive as a static record. They will not appear in your new instance’s public timeline, profile, or search results. The media attachments are also not restored automatically; they are stored locally in the archive for your reference but are not uploaded to the new server.

What You Can Restore

You can restore the following lists by importing their corresponding CSV files:

• Following list (who you followed)
• Followers list (who followed you — this is informational only; the new instance cannot force old followers to follow you)
• Blocked accounts
• Muted accounts
• Domain blocks

The followers list CSV is useful for manually finding and reconnecting with people who followed you, but Mastodon does not automatically re-establish those connections. Each user must follow you again on your new instance.

What You Cannot Restore

The following items cannot be imported into a new instance from the archive:

• Your old posts, boosts, and replies
• Media attachments from old posts
• Direct messages (they are not included in the export at all)
• Your profile display name, bio, header image, and avatar
• Your bookmarks and lists (list memberships are not exported)

Steps to Import the Export Archive into a New Mastodon Instance

1. Log in to your new Mastodon instance
   Open your web browser and go to the instance where you created your new account. Enter your email and password to access your account dashboard.
2. Navigate to the import settings
   Click the gear icon or your profile avatar to open Preferences. From the left menu, select Import and export, then click the Import tab.
3. Choose the type of data to import
   From the dropdown menu labeled “Import type,” select the category that matches the CSV file you want to upload. Options include Following list, Blocking list, Muting list, and Domain blocking list. You must repeat this process for each CSV file separately.
4. Upload the CSV file
   Click the Choose file button and locate the corresponding CSV file from your extracted archive. For example, to restore who you followed, select the following_accounts.csv file. After selecting the file, click the Upload button.
5. Confirm the merge behavior
   A dialog box appears asking whether you want to merge the imported list with your current list or replace it entirely. Choose Merge to add the imported accounts to your existing list, or Override to replace the current list with the imported one. Click Confirm to start the import.
6. Wait for the import to complete
   Mastodon processes imports as a background task. Depending on the size of the list, this may take a few seconds to several minutes. A notification appears when the import finishes. Do not close the browser tab during processing.
7. Repeat for each CSV file
   Return to the Import tab and repeat steps 3 through 6 for blocking_accounts.csv, muting_accounts.csv, and domain_blocks.csv if you want to restore those lists as well.
8. Manually restore your profile and media
   Go to Preferences > Appearance to set your display name and bio. Upload your avatar and header image from the media_attachments folder in your archive. These settings are not imported automatically.

Common Issues When Restoring a Mastodon Archive

CSV File Format Errors During Import

If Mastodon rejects your CSV file, the most common cause is a mismatch in column headers. The import system expects specific column names. Open the CSV file in a plain text editor and verify that the first row contains exactly: Account address, Show boosts. Each subsequent row must contain the full ActivityPub address of the account, such as @user@instance.social. Remove any extra columns or empty rows before re-uploading.

Followers List Does Not Restore Connections

Many users expect that importing the followers CSV will automatically make those accounts follow them on the new instance. This is not supported. The followers CSV is provided for your reference only. To reconnect with your old followers, you must publish a post on your new account announcing the move and ask them to follow you there. Alternatively, use the Move account feature under Preferences > Account > Move to a different account if you still have access to your old instance.

Media Attachments Not Visible After Import

The media_attachments folder in your archive contains your old images and videos, but Mastodon does not provide a bulk upload mechanism for these files. To add media to new posts, you must upload each file individually through the compose box. There is no way to attach old media to old posts because those posts were not imported.

Import Process Stuck or Fails Silently

If the import button does not respond or the page refreshes without a success message, the CSV file may be too large for your instance’s upload limit. Split the CSV into smaller files of 500 rows each and import them one at a time. Also ensure that your browser allows pop-ups and notifications from the instance domain, as the completion notice may be blocked.

Item	Archive Download	Import to New Instance
Following list	Exported as following_accounts.csv	Imported via Preferences > Import
Followers list	Exported as followers.csv	Not importable; reference only
Blocked accounts	Exported as blocking_accounts.csv	Imported via Preferences > Import
Muted accounts	Exported as muting_accounts.csv	Imported via Preferences > Import
Domain blocks	Exported as domain_blocks.csv	Imported via Preferences > Import
Old posts	Exported as outbox.html	Not importable
Media attachments	Exported as media_attachments folder	Not importable; upload manually

After completing the import steps, your new instance will reflect the following, blocking, muting, and domain blocking lists from your old account. Your old posts remain accessible only in the outbox.html file on your local computer. To preserve your posting history for future reference, keep the archive in a safe location. If you want your old followers to find you, consider using the Move account feature from your old instance before it becomes inaccessible. This feature sends a one-time notification to all your followers with your new account address.