Removing Built-In Emoji - Unsupported. Use with caution

:stop_sign:WARNING: The following instructions are for advanced users. Please proceed with caution​:stop_sign:

:information_source:NOTE: If you operate a highly-available Mattermost cluster these steps must be applied to all Mattermost Server application nodes​:information_source:

:warning:These changes will need to be re-applied any time there is an upgrade to Mattermost server​:warning:

There are a variety of reasons why you may need to remove the built in emojis that Mattermost ships with. For this post I’ll bucket them all under one heading of “Not appropriate for end-user community”.

Mattermost ships with a large library of existing emoji that is similar to what is available through your device operating system keyboard (see our docs on how to access the OS/keyboard emoji on different clients), but not exactly the same. The following steps explain how you can manually remove a specific emoji from the Mattermost client. Note, this will not affect the emoji that are available from your keyboard.

  1. Identify the name of the emoji you want to remove. On the desktop client you can open the emoji picker and hover over the one you want to remove. In the following screenshot I’m hovering over the poop emoji, so the name is hankey. Make note of this term, and the other terms which are aliases of this emoji.
  2. Under the Mattermost installation directory INSTALL_DIR (typically /opt/mattermost) navigate to the INSTALL_DIR/client
  3. There are 2 files you’ll need to edit and they are very dense with characters (these are minified/process javascript files). First you need to find the files.
/opt/mattermost/client$ grep -o hankey *

Here we have our 2 files: :one: main.0f2d0e1224bffaa8a2da.js, and

Note: The files are very large minified javascript, so some editors may have a hard time. I used vim for this

  1. Backup the js file :one: somewhere in case you make a mistake. Open the js file and search for the emoji you want to remove. There are 2 places where the emoji should appear:

a) See following image. All 3 versions of the poop emoji are listed (“hankey”, “poop”, “shit”). We need to remove all of this [\"hankey\",79],[\"poop\",79],[\"shit\",79], (NOTE: The trailing comma must be removed too… this is part of a list). Save the file in place.

b) See the following screenshot. Remove the entire json block (including trailing comma) that starts with “aliases” {"aliases":["hankey","poop","shit"],"filename":"1f4a9","category":"people","batch":"2"},

5. Backup the file :two: somewhere in case you make a mistake. Open the file and search for the emoji you want to remove the same as in step 4. All 3 versions need to be removed. This file was extra tricky as the size really made my editor slow down. Save the file in places.

  1. Hard refresh your Mattermost client (CTRL/CMD-R).

  2. Search the emoji picker for the emoji you just deleted. Confirm it is no longer available.

Let me know if you have any questions.


Feedback from a developer:

you can probably skip editing the source map ( .map ) file - that’s just information for JS debuggers

I haven’t tested yet.

1 Like

FYI - An issue was discovered with the above approach. The approach results in emoji being shifted in the UI, and images are not aligned to their correct emoji… which further emphasizes the risks of going this route. But if you absolutely MUST remove an emoji for some reason, these steps below seem to work as well:

  1. Restore the 2 files you edited to remove the problematic emoji (one was *.js , and one was * ). They should be back to their original state, where they would show the problematic emoji. Remember to do this on all 3 app servers.
  2. Again, going into those same 2 files, you’re going to do something different. Instead of removing blocks that related to the emoji, you’re now going to edit them with a different name, and have them point to a different (blank) file.

So, for me, my files have modifications like this:

main.a899b9c055b3c3ecbac7.js :



Finally, copy the attached transparent png file transparent-64x74.png under the following folder:



thanks for the awesome information.

This approach is no longer valid as of Mattermost v5.37.

I am looking into other ways to accomplish this and will feedback when I come up with something.

1 Like