How to Export Mastodon Filters With Custom Keywords

Mastodon filters let you hide posts containing specific words or phrases from your home and public timelines. You may have built a long list of custom keywords to block spoilers, trigger words, or specific topics. Exporting those filters lets you back them up or move them to a new instance without retyping every entry.

Mastodon includes a built-in export tool that saves filters as a CSV file. This file contains each filter, its keywords, and the action you set. You can use this file to restore filters on the same account or import them into a different Mastodon account.

This article explains the exact steps to export filters with custom keywords from Mastodon. It also covers the file format, common mistakes, and what to do if the export fails.

How Mastodon Filter Export Works

Mastodon stores filters server-side in your account database. Each filter has a title, a list of keywords, an action, and an optional expiration time. The action can be hide or warn. The title is the label you see in your filter list.

The export tool creates a CSV file containing all your filters. The CSV file uses the following columns:

• Title: The name you gave the filter.
• Keyword: All keywords for that filter, separated by a pipe character.
• Filter action: Either hide or warn.
• Expires in: The number of seconds until the filter expires, or empty if it never expires.
• Keywords are context: Each keyword can have a context, such as home, public, notifications, or conversation. This is part of the keyword data.
• Whole word: A boolean flag indicating whether the keyword must match whole words only.

The CSV file does not include filter context settings directly. The keyword context and whole word flag are embedded in the keyword data. When you reimport the file, Mastodon recreates the filters with their original contexts if the format matches.

You must be logged into your Mastodon account to export filters. The export feature is available on all Mastodon instances running version 4.0 or later. Older instances may not support filter export.

Steps to Export Filters From Mastodon

Follow these steps to download your filters as a CSV file. The process takes less than one minute.

1. Open Mastodon preferences
   Click the preferences icon in the top-right corner of the Mastodon web interface. The icon looks like a gear or a person silhouette depending on your theme. Select Preferences from the dropdown menu.
2. Navigate to Import and export
   In the left sidebar, click Import and export. This page lists all data export options for your account.
3. Click the Export button for filters
   Look for the section labeled Export. Find the row that says Filters. Click the Export button to the right of the Filters label. The browser downloads a file named mastodon_filters.csv.
4. Open the CSV file to verify contents
   Open the downloaded file in a text editor or spreadsheet application. Each row represents one filter. The first row contains column headers: Title, Keyword, Filter action, Expires in, Keywords are context, Whole word. Check that your custom keywords appear in the Keyword column, separated by pipe characters. If the file is empty or missing rows, repeat the export process.

The CSV file uses UTF-8 encoding. If you open it in Excel on Windows, you may need to import the file using the Data > From Text/CSV option to see special characters correctly.

Common Mistakes When Exporting Mastodon Filters

Exported CSV file is empty

If the downloaded file contains only headers and no data rows, you have no filters defined. Create at least one filter with one keyword before exporting. Go to Preferences > Filters and click Add new filter. Enter a title and keyword, then save the filter. Export again.

Keywords appear jumbled or missing after import

The CSV file uses the pipe character as a delimiter between keywords within a single cell. If a keyword contains a pipe character, the export tool may split it incorrectly. Avoid using pipe characters in your keywords. If you already have such keywords, edit them before exporting.

Filter contexts are not preserved during reimport

The CSV file stores keyword context data in the Keywords are context column. Not all Mastodon versions support this column during import. If you import the file into an older instance, the contexts may reset to the default context. Check your Mastodon instance version before importing.

Export button is missing or grayed out

The filter export feature requires Mastodon version 4.0 or later. If you are on an older instance, update the instance software or ask your admin to upgrade. Alternatively, use the Mastodon API to export filters manually via a script.

Mastodon Filter Export vs Manual Backup

Item	CSV Export	Manual Copy
Time required	Less than one minute	10 to 30 minutes depending on filter count
Accuracy	Exact copy of all keywords and actions	Prone to typos and missed entries
Compatibility	Works with any Mastodon instance running version 4.0 or later	No software version requirement
Reimport support	Built-in import tool on the same page	Must re-enter each filter manually
Context preservation	Preserves keyword context if the import instance supports it	Context is lost unless manually noted

Manual backup involves copying each filter title and keyword list into a text file. This method is slower and error-prone. Use the CSV export for reliable backups and migrations.

After exporting, you can import the CSV file into a new Mastodon account by going to Preferences > Import and export > Import. Select the file type Filters and upload the CSV file. Mastodon recreates all filters with their original keywords and actions. Check the filter list after import to confirm everything transferred correctly.

If you need to edit filters before reimporting, open the CSV file in a spreadsheet editor. Modify the Keyword column, adding or removing pipe-separated keywords. Save the file as a CSV with UTF-8 encoding, then import it.