How to Export Mastodon Custom Emoji as Image Set

Mastodon instances often include hundreds of custom emoji that you cannot use on other servers. You might want to back up these emoji for personal use or migrate them to another instance. The built-in Mastodon export feature does not include custom emoji. This article explains how to use a browser script and a manual method to download all custom emoji from any Mastodon instance as an image set.

What the Mastodon Custom Emoji API Provides

Mastodon exposes a public API endpoint that lists all custom emoji on an instance. The endpoint is /api/v1/custom_emojis. It returns a JSON array containing each emoji’s shortcode, static URL, and animated URL. This data is available to any visitor, not just logged-in users. The emoji files are typically PNG for static images and GIF for animated ones. An instance can host hundreds or thousands of emoji, making manual downloading impractical. The methods below use this API to automate the export.

Prerequisites for Exporting Emoji

You need a modern web browser such as Chrome, Firefox, or Edge. For the manual admin method, you must have admin or moderator access to the Mastodon instance. For the command-line method, you need Python 3.6 or later installed on your computer. No special permissions are required for the browser console method.

Steps to Export Custom Emoji Using Browser Developer Tools

This method works on any Mastodon instance. It uses the browser’s developer console to fetch all emoji URLs and trigger downloads.

1. Open your Mastodon instance in the browser
   Navigate to any page on the instance, such as the public timeline or a local profile. The script will fetch emoji from the instance you are currently visiting.
2. Open the browser developer console
   Press Ctrl+Shift+J on Windows or Cmd+Option+J on macOS. In Firefox, you can press Ctrl+Shift+K.
3. Paste the emoji export script into the console
   Copy the following JavaScript code and paste it into the console prompt, then press Enter:
   fetch('/api/v1/custom_emojis').then(r=>r.json()).then(emojis=>{emojis.forEach(e=>{let a=document.createElement('a');a.href=e.static_url;a.download=e.shortcode+'.png';document.body.appendChild(a);a.click();document.body.removeChild(a)})})
4. Wait for all downloads to complete
   The browser will begin downloading each emoji as a separate file. The number of downloads equals the number of custom emoji on the instance. Depending on the instance size, this may take several minutes. Do not close the browser tab until all downloads finish.
5. Organize the downloaded files
   After the downloads finish, move all files to a single folder. The filenames are the shortcodes with a .png extension. If you need the animated versions, modify the script to use e.url instead of e.static_url.

Steps to Export Custom Emoji as Instance Admin

If you are an admin of the Mastodon instance, you can export all custom emoji directly from the administration panel. This method downloads a single ZIP file containing all emoji images.

1. Log in to your Mastodon instance with an admin account
   Use your admin or moderator credentials. Only users with the appropriate role can access the admin panel.
2. Navigate to Preferences > Administration > Custom Emoji
   Click your profile avatar in the top-right corner, select Preferences, then click Administration in the left sidebar. Finally, click Custom Emoji.
3. Click the Export button
   At the top of the Custom Emoji page, locate the Export button. It is labeled Export .CSV. This exports a CSV file listing all emoji shortcodes and their image URLs, not the actual image files.
4. Download each emoji manually from the CSV list
   Open the CSV file in a spreadsheet application. Each row contains a shortcode and a URL. You can use a bulk download tool such as wget or a browser extension to download all URLs listed in the CSV.
5. Use the Admin API for a direct ZIP export
   Some Mastodon versions support a ZIP export via the admin API. Send a GET request to /admin/custom_emojis/export.zip while authenticated as an admin. If the endpoint is not available, the browser console method is the best alternative.

Common Issues and Limitations When Exporting Emoji

Browser Blocks Multiple Downloads

Most browsers show a pop-up asking for permission to allow multiple downloads. Click Allow or Always Allow to proceed. If you miss the prompt, the script may stop after a few files. Reload the page and run the script again, ensuring you approve the multiple download request.

Some Emoji Files Are Animated GIFs

The script above downloads static PNG versions. To get animated GIF versions, replace e.static_url with e.url in the script. Note that some emoji may only have a static version. The API returns both fields for each emoji when available.

Large Instances Cause Browser Slowdown

If the instance has more than 500 emoji, the browser may become unresponsive or crash. In this case, use the command-line Python tool instead. It downloads files sequentially without loading the browser UI.

Browser Console Script vs Admin Export vs Python Tool

Item	Browser Console Script	Admin CSV Export	Python Tool (mastodon-emoji-exporter)
Access level required	None	Admin or moderator	None
Output format	Individual image files	CSV list of URLs	Individual image files in a folder
Handles animated emoji	Yes, with script modification	No, only URLs	Yes, automatically
Best for	Quick one-time export	Admins who need a record	Large instances and automation

You can now export custom emoji from any Mastodon instance as an image set. For a quick export, use the browser console script. For repeated exports or large instances, install the mastodon-emoji-exporter Python tool from GitHub. After exporting, you can upload the emoji to another instance via the admin panel using the Import button on the Custom Emoji page. The import function accepts a ZIP file containing the images and a JSON or CSV mapping file.