Mastodon Export Bookmarks: How to Save and Re-Apply

Mastodon bookmarks let you save posts you want to revisit later. Unlike favorites, bookmarks are private and not shared with the original author. If you switch instances or need a local backup, you can export your bookmarks as a JSON file. This article explains how to export your Mastodon bookmarks and re-apply them on a new account or after a reset.

The built-in export tool in Mastodon produces a file that contains all your bookmarked posts. The file includes the post URL, author, and timestamp. You can store this file for personal reference or use third-party tools to import it back into a different account. However, Mastodon does not provide a native import feature for bookmarks. You will need to use a script or a web app to restore them.

This guide covers the exact steps to export bookmarks, the limitations of the export format, and the available methods to re-apply bookmarks on a new account. You will also learn what data is preserved and what is lost during the process.

How Mastodon Bookmark Export Works and Its Limitations

Mastodon stores bookmarks as a list of post IDs linked to your account. When you export your data, the system creates a JSON file that contains each bookmarked post’s URL, the post author’s username, the post content (in plain text), and the timestamp when you bookmarked it. This file is a snapshot of your bookmarks at the time of export.

The export file does not include the original post’s media, embeds, or full thread context. It only stores the post URL and the first 500 characters of the post text. This is enough to identify the post but not to display it in full.

The main limitation is that Mastodon does not offer a native import function for bookmarks. You cannot upload the JSON file back into the same account or a different account through the web interface. To re-apply bookmarks, you must use a third-party tool that calls the Mastodon API to bookmark each post individually. These tools require you to authorize access to your new account and then process the exported file.

Another limitation is that the exported file only contains posts that still exist on the original server. If the original post has been deleted by the author or removed from the instance, the URL will be invalid. The import tool will skip such posts or fail to bookmark them.

Steps to Export Bookmarks from Your Mastodon Account

Follow these steps to download a complete backup of your bookmarks. The export includes all other data types by default, but you can select only bookmarks in the export interface.

1. Open the Export page
   In your Mastodon web interface, click the Preferences link in the right column. Then select Import and export from the menu. Click the Export tab at the top of the page.
2. Select the data types to export
   Scroll to the Data export section. You will see a list of checkboxes for different data types. Check the box labeled Bookmarks. Uncheck any other boxes if you only want bookmarks. If you want a full backup, leave all boxes checked.
3. Generate the export file
   Click the Export button. Mastodon will create a CSV file for each selected data type. The bookmarks file is named bookmarks.csv. Your browser will download the file automatically.
4. Save the file securely
   Store the downloaded CSV file in a safe location. The file contains public post URLs and your Mastodon account username. It does not contain your password or access tokens.

The exported CSV file has columns for URL, Account, Created at, and Content. The URL column contains the full link to the bookmarked post. The Content column contains the first 500 characters of the post text.

Steps to Re-Apply Bookmarks to a Different Mastodon Account

Because Mastodon does not have a native bookmark import, you must use a third-party tool. The most reliable method is the Mastodon Bookmark Import Tool hosted at mastodon-bookmark-import.glitch.me. This tool reads your exported CSV file and uses the Mastodon API to bookmark each post on your new account.

1. Prepare the exported CSV file
   Make sure you have the bookmarks.csv file from the export step. Do not modify the file. The tool expects the exact column structure that Mastodon produces.
2. Open the import tool in a browser
   Navigate to mastodon-bookmark-import.glitch.me. This is a community-maintained web app. It does not store your data. All processing happens in your browser.
3. Authorize the tool to access your new account
   Click the Log in with Mastodon button. Enter the domain of your new Mastodon instance (for example, mastodon.social). Click Authorize. The tool will request permission to read and write your bookmarks. Grant the permission.
4. Upload the exported CSV file
   After authorization, you will see a file upload area. Click Choose File and select your bookmarks.csv file. The tool will parse the file and display a preview of the posts it found.
5. Start the import process
   Click the Import Bookmarks button. The tool will process each URL one by one. It will skip any post that no longer exists or that belongs to a blocked instance. The process may take several minutes if you have many bookmarks.
6. Verify the imported bookmarks
   After the import completes, go to your new Mastodon account. Open the Bookmarks section from your profile menu. You should see all the posts that were successfully imported. Posts that failed due to deletion or inaccessibility will not appear.

If you prefer a command-line approach, you can use the mastodon-bookmark-import Python script available on GitHub. This script requires you to generate an access token from your Mastodon account settings and run the script locally.

Common Issues with Bookmark Export and Re-Apply

Exported CSV file is empty or missing bookmarks

If your exported CSV file contains no rows, you may not have any bookmarks in your account. Verify your bookmarks by opening the Bookmarks section in your Mastodon web interface. If you see bookmarks there, try the export again. Ensure you checked the Bookmarks checkbox before clicking Export.

Import tool shows error: invalid file format

The import tool expects the exact CSV format from Mastodon. If you edited the file or opened it in a spreadsheet program that changed the formatting, the tool may reject it. Download a fresh export and upload it without any modifications. Do not change the file extension or column order.

Some bookmarks are missing after import

Posts that were deleted by the original author or removed from the instance will not be imported. The import tool attempts to fetch each URL. If the server returns a 404 or 410 error, the tool skips that post. This is expected behavior. You can check the import log in the tool to see which URLs failed.

Authorization fails for the import tool

Some Mastodon instances block third-party applications from creating access tokens. If you see an error during authorization, check your instance’s moderation policies. You may need to use a different tool or run the script locally with a personal access token. To generate a token, go to Preferences > Development > New Application, grant the read:bookmarks and write:bookmarks scopes, and copy the access token.

Mastodon Bookmark Export vs Third-Party Import Tool

Item	Native Export	Third-Party Import Tool
Purpose	Backup bookmarks to a local file	Restore bookmarks to a different account
File format	CSV with columns: URL, Account, Created at, Content	Reads the same CSV file
Requires authorization	No	Yes, OAuth token from the new account
Handles deleted posts	Exports the URL regardless of post existence	Skips posts that return 404 or 410

Mastodon provides no native import for bookmarks. The export is a one-way backup. To move bookmarks to a new account, you must rely on community tools. Always test the import on a small set of bookmarks before processing a large file.

After successfully importing your bookmarks, you can organize them using Mastodon’s built-in bookmark categories. To create a category, open the Bookmarks section, click the three-dot menu on a bookmarked post, and select Add to category. This feature helps you group bookmarks by topic. You can also use the search bar in the Bookmarks section to filter posts by keyword.

If you plan to migrate instances frequently, consider using a bookmark management service that syncs with Mastodon via the API. Services like Bookmarky or Raindrop.io can automatically save bookmarks from multiple Mastodon accounts. However, these services require ongoing authorization and may not be suitable for privacy-sensitive users.

For advanced users, the Mastodon API allows you to write a custom script that exports and imports bookmarks in your preferred format. You can use the GET /api/v1/bookmarks endpoint to fetch all bookmarks and the POST /api/v1/statuses/:id/bookmark endpoint to add them. This gives you full control over the process and lets you handle errors more precisely than a generic tool.