Mastodon Bookmarks Export and Re-Import Walkthrough

You bookmarked posts in Mastodon to read later. Now you need to move those bookmarks to a new instance or keep a local backup. Mastodon does not sync bookmarks across instances automatically. This walkthrough shows how to export your bookmarks as a CSV file and re-import them into another Mastodon account so you keep every saved post.

Bookmarks are stored per account on a single instance. When you switch instances or start a new account, your bookmarks stay behind. The export tool in Mastodon’s settings lets you download a CSV file containing the URL and author of each bookmarked post. You can then upload that CSV to a new account using a compatible import tool.

This article covers the exact steps for exporting bookmarks from the web interface, preparing the CSV file, and re-importing the bookmarks into a different Mastodon account. It also explains common issues such as missing posts and duplicate entries.

How Mastodon Bookmarks Are Stored and Why Export Is Needed

Mastodon bookmarks are stored in the database of your current instance. Each bookmark links to a remote post’s URL and the author’s account. When you switch to a different instance, your new account has an empty bookmarks list. No cross-instance sync exists.

The export feature in Mastodon’s settings creates a CSV file with three columns: Bookmark URL, Account URL, and Created at. The CSV does not include the post content, media, or boosts. It only stores the link and the author’s address.

Re-importing requires a method that can call the Mastodon API to create bookmarks one by one. The built-in import tool in Mastodon supports following lists, mute lists, and block lists, but not bookmarks. Therefore, you must use a script or a third-party service to upload the CSV.

What the CSV File Contains

The exported CSV file uses commas as delimiters. The first row is a header row with these column names:

• Bookmark URL – The full URL of the bookmarked post.
• Account URL – The full URL of the author’s Mastodon profile.
• Created at – The timestamp of when the bookmark was created in ISO 8601 format.

Each subsequent row contains one bookmark. If the CSV contains duplicate URLs, the import script may create duplicate bookmarks in the new account.

Steps to Export Bookmarks from Mastodon

1. Open Mastodon Settings
   Log in to your Mastodon instance. Click the gear icon in the top-right menu or navigate to the Settings page directly using the URL https://yourinstance.com/settings.
2. Go to Import and Export
   In the left sidebar, click Import and Export. This page shows options for exporting your data and importing lists.
3. Click the Export Tab
   At the top of the Import and Export page, click the Export tab. You will see a list of data types that can be exported.
4. Select CSV for Bookmarks
   Find the row labeled Bookmarks. Click the CSV button next to it. Your browser will download a file named bookmarks.csv.
5. Save the CSV File
   Store the CSV file in a secure location. Do not share it publicly because it contains URLs that may reveal your reading habits.

After downloading, open the CSV in a text editor or spreadsheet application to verify the data. Expect one row per bookmark. If you have zero bookmarks, the CSV will contain only the header row.

Steps to Re-Import Bookmarks into a New Mastodon Account

Mastodon’s built-in import tool does not support bookmark CSV files. You must use an API-based method. The following steps show how to use a Python script to re-import the bookmarks.

Prerequisites for Re-Import

• Python 3.6 or later installed on your computer.
• The requests library installed: pip install requests.
• An access token for your new Mastodon account. Create one in Preferences > Development > New Application. Grant the write:bookmarks scope.

Re-Import Using a Python Script

1. Create the Script File
   Open a text editor and paste the following code. Replace your-instance.com with your new instance domain and your-access-token with the token you generated.
   import csv
   import requests

   instance = 'https://your-instance.com'
   token = 'your-access-token'
   headers = {'Authorization': f'Bearer {token}'}

   with open('bookmarks.csv', newline='', encoding='utf-8') as csvfile:
reader = csv.DictReader(csvfile)
for row in reader:
url = row['Bookmark URL']
response = requests.post(f'{instance}/api/v1/bookmarks', headers=headers, json={'url': url})
if response.status_code == 200:
print(f'Imported: {url}')
else:
print(f'Failed: {url} - {response.status_code}')

2. Place the Script and CSV in the Same Folder
   Save the script as import_bookmarks.py. Place your bookmarks.csv file in the same folder.
3. Run the Script
   Open a terminal or command prompt. Navigate to the folder containing the script. Run python import_bookmarks.py. The script will create a bookmark for each URL in the CSV.
4. Verify the Import
   Log in to your new Mastodon account. Open your bookmarks page. You should see all the imported posts listed.

Common Issues When Exporting and Re-Importing Bookmarks

Exported CSV Contains No Bookmarks

If the downloaded CSV has only a header row, you have no bookmarks in your current account. Open the bookmarks page in Mastodon and confirm that posts appear there. Only posts you bookmarked using the bookmark icon (the ribbon symbol) are included.

Import Script Returns 422 Unprocessable Entity

A 422 error usually means the URL in the CSV is malformed or the post has been deleted. Check the CSV for truncated URLs or extra spaces. Remove any rows that point to deleted posts and run the script again.

Duplicate Bookmarks After Re-Import

The script does not check for existing bookmarks. If you run the script twice, you will get duplicate entries. To avoid this, run the script only once. If duplicates appear, you can remove them manually using the bookmark icon on each post.

Bookmark URL from a Different Instance Fails

Mastodon can bookmark posts from any federated instance. The API call uses the post’s public URL. If the remote instance is down or defederated, the bookmark creation may fail. The script will print a failure message for that URL. You can skip that row manually.

Mastodon Bookmark Export vs Third-Party Backup Tools

Item	Built-in CSV Export	Third-Party Backup Tool
Data included	Bookmark URL, author URL, timestamp	Full post content, media, and metadata
Re-import method	Requires API script or third-party app	Direct import via tool’s interface
Privacy risk	CSV file stored locally	Data sent to third-party server
Cost	Free	May require subscription or donation
Automation	Manual export and script run	Scheduled backups possible

Choose the built-in export if you want full control and privacy. Choose a third-party tool if you need automatic backups or want to preserve post content.

You can now export your Mastodon bookmarks to a CSV file and re-import them into a new account using a simple Python script. The process preserves the URLs and author references for each bookmarked post. For future migrations, consider setting up a regular export schedule to keep your CSV up to date. If you manage multiple accounts, the same script can be adapted to handle batch imports by looping over multiple CSV files.