Install & Compatibility
Where this runs
tested against v2.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.114s · 22.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.104s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
emojize
✓ import emoji
text_with_emoji = emoji.emojize('Python is :thumbs_up:')
✗ from emoji import emojize
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
✓ import emoji
text_with_shortcodes = emoji.demojize('Python is 👍')
✗ from emoji import demojize
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='')
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}")
Debug
Known issues
breakingVersion 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()`.fixReview 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.
affects: >=2.0.0
breakingThe `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.fixIf you used `get_emoji_regexp()` for removing emojis, switch to `replace_emoji()`. For extracting emojis, use `emoji.emoji_list()` or `emoji.analyze()` as replacements.
affects: >=2.0.0
breakingSupport 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.fixUpgrade 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'`).
affects: >=2.5.0
gotchaInconsistent 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.fixEnsure 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.
affects: All
gotchaPotential `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.fixAlways 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')`. affects: All
gotchaAliases (`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.fixWhen 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')`. affects: <2.x (pre-2.x versions might issue warnings for this specific scenario), All (behavioral)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'emoji'
The 'emoji' library is not installed in the Python environment being used, or the Python interpreter cannot find it.
fixRun `pip install emoji` in your terminal or command prompt to install the library for your active Python environment.
AttributeError: module 'emoji' has no attribute 'emojize'
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.
fixRename 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`.
AttributeError: module 'emoji' has no attribute 'unicode_emoji'
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.
fixUpdate 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`.
AttributeError: module 'emoji' has no attribute 'get_emoji_regexp'
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.
fixReplace 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.
Emoji shortcodes like ':earth_asia:' are not converted to emojis by `emojize()` and remain as shortcodes in the output.
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.
fixPass 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). Upgrade
Version history
2.15.0latest on PyPI · released Sep 21, 2025
Audit
Dependencies
No dependency data recorded yet.