Emoji for Python

2.15.0 verified Tue May 12 auth: no python install: verified

The `emoji` library provides comprehensive support for handling Unicode emojis in Python, allowing conversion between emoji characters and their shortcodes (e.g., 👍 to :thumbs_up:). It supports the entire set of Emoji codes defined by the Unicode consortium and various languages. The library is actively maintained, with version 2.15.0 being the latest, and typically releases updates to keep up with Unicode emoji standards.

pip install emoji

Common errors

error ModuleNotFoundError: No module named 'emoji' ↓

cause The 'emoji' library is not installed in the Python environment being used, or the Python interpreter cannot find it.

fix

Run pip install emoji in your terminal or command prompt to install the library for your active Python environment.

error AttributeError: module 'emoji' has no attribute 'emojize' ↓

cause This error commonly occurs when there is a file named `emoji.py` in the same directory as your script, leading to a circular import, or if an incompatible package like `django-emoji` was installed instead of the official `emoji` library.

fix

Rename any local file named emoji.py to avoid conflict, or uninstall django-emoji (if present) using pip uninstall django-emoji and then install the correct emoji library with pip install emoji.

error AttributeError: module 'emoji' has no attribute 'unicode_emoji' ↓

cause The `unicode_emoji` attribute was removed in version 2.x of the `emoji` library. Code written for older versions (pre-2.0) that tries to access this attribute will fail with current versions.

fix

Update your code to use the current API, such as emoji.EMOJI_DATA for emoji data or emoji.is_emoji() for checking emoji characters. Alternatively, if strict compatibility with older code is needed, downgrade the package to version 1.7.0 using pip install emoji==1.7.0.

error AttributeError: module 'emoji' has no attribute 'get_emoji_regexp' ↓

cause The `get_emoji_regexp()` function was removed in version 2.0.0 of the `emoji` library because internal emoji scanning no longer relies on regular expressions.

fix

Replace calls to emoji.get_emoji_regexp() with emoji.replace_emoji() to remove emojis from a string, or emoji.emoji_list() to extract emojis from a string.

error Emoji shortcodes like ':earth_asia:' are not converted to emojis by `emojize()` and remain as shortcodes in the output. ↓

cause By default, the `emojize()` function only converts official CLDR (Common Locale Data Repository) shortcodes. Many commonly used shortcodes are aliases and require explicit activation of the 'alias' language or another specific language.

fix

Pass the language='alias' argument to the emojize() function to enable conversion of additional aliases (e.g., emoji.emojize(':thumbs_up:', language='alias')). If using non-English shortcodes, specify the appropriate language code (e.g., language='es' for Spanish).

Warnings

breaking Version 2.0.0 introduced breaking changes concerning non-English short codes. The names of emoji in non-English languages were updated to Unicode CLDR version 41, meaning some previously stored non-English :short-code-emoji: might no longer work or be ignored by `emojize()`. ↓

fix Review and update any stored or generated non-English emoji shortcodes according to the new Unicode CLDR version 41 definitions. Test `emojize()` behavior with affected languages.

breaking The `get_emoji_regexp()` function was removed in version 2.0.0. The internal mechanism for scanning emojis no longer relies on regular expressions due to performance and accuracy issues with complex Unicode emoji sequences. ↓

fix If you used `get_emoji_regexp()` for removing emojis, switch to `replace_emoji()`. For extracting emojis, use `emoji.emoji_list()` or `emoji.analyze()` as replacements.

breaking Support for Python 2.7, 3.4, and 3.5 was removed in version 2.5.0. The library now requires Python 3.8 or newer. ↓

fix Upgrade your Python environment to version 3.8 or newer. If stuck on older Python versions, use `emoji` v2.4.0 or earlier (e.g., `pip install 'emoji<2.5.0'`).

gotcha Inconsistent emoji rendering across platforms and terminals. Emojis are Unicode characters, but their visual representation depends on the font support and rendering capabilities of the environment where the Python script is run. ↓

fix Ensure your terminal, operating system, and fonts support the specific Unicode emoji versions you are using. Test your output in target environments. This is often outside the library's direct control.

gotcha Potential `UnicodeEncodeError` when handling emoji. This often occurs when text containing emojis is processed or written to a file/output stream using an encoding that does not support the full range of Unicode characters, such as ASCII instead of UTF-8. ↓

fix Always explicitly use 'utf-8' encoding when opening files, communicating with databases, or handling HTTP requests/responses that might contain emojis. For example, `open('file.txt', 'w', encoding='utf-8')`.

gotcha Aliases (`language='alias'`) for `emojize()` and `demojize()` are specific to English. Using `language='alias'` with other languages might not produce expected results or could lead to warnings in older versions. ↓

fix When working with non-English languages, rely on the official CLDR shortcodes for those languages. Avoid mixing `language='alias'` with non-English `language` settings. Load specific language configurations as needed, e.g., `emoji.config.load_language('es')`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.09s 22.2M

3.10 alpine (musl) - - 0.10s 22.2M

3.10 slim (glibc) wheel 1.5s 0.06s 23M

3.10 slim (glibc) - - 0.06s 23M

3.11 alpine (musl) wheel - 0.12s 24.1M

3.11 alpine (musl) - - 0.14s 24.1M

3.11 slim (glibc) wheel 1.6s 0.11s 25M

3.11 slim (glibc) - - 0.10s 25M

3.12 alpine (musl) wheel - 0.14s 15.9M

3.12 alpine (musl) - - 0.15s 15.9M

3.12 slim (glibc) wheel 1.4s 0.14s 16M

3.12 slim (glibc) - - 0.16s 16M

3.13 alpine (musl) wheel - 0.13s 15.7M

3.13 alpine (musl) - - 0.14s 15.6M

3.13 slim (glibc) wheel 1.4s 0.13s 16M

3.13 slim (glibc) - - 0.14s 16M

3.9 alpine (musl) wheel - 0.09s 21.7M

3.9 alpine (musl) - - 0.10s 21.7M

3.9 slim (glibc) wheel 1.7s 0.07s 22M

3.9 slim (glibc) - - 0.09s 22M

Imports

emoji
```
import emoji
```
emojize
wrong
```
from emoji import emojize
```
correct
```
import emoji
text_with_emoji = emoji.emojize('Python is :thumbs_up:')
```
While 'from emoji import emojize' works, the common and recommended pattern for this library is to import the module itself and call functions as `emoji.emojize()` to avoid potential name collisions and align with documentation examples.

demojize

wrong

from emoji import demojize

correct

import emoji
text_with_shortcodes = emoji.demojize('Python is 👍')

See note for `emojize`.

analyze

import emoji
emoji_data = list(emoji.analyze('Python is 👍'))

replace_emoji

import emoji
clean_text = emoji.replace_emoji('Python is 👍', replace='')

Quickstart last tested: 2026-04-24

The quickstart demonstrates the primary functions: `emojize` for converting text shortcodes to Unicode emojis, `demojize` for converting Unicode emojis back to shortcodes, `analyze` for extracting emoji information, and `replace_emoji` for substituting emojis with other strings.

import emoji

# Convert shortcodes to emoji
emojified_text = emoji.emojize('Python is fun :red_heart: :snake:')
print(f"Emojified: {emojified_text}")

# Convert emoji to shortcodes
demojified_text = emoji.demojize('Python is fun ❤️🐍')
print(f"Demojified: {demojified_text}")

# Analyze text for emojis
emojis_found = list(emoji.analyze('Hello 👋 world 🌍'))
print(f"Emojis found: {emojis_found}")

# Replace emojis with a custom string
text_without_emojis = emoji.replace_emoji('Hello 👋 world 🌍', replace='[emoji]')
print(f"Text without emojis: {text_without_emojis}")