emoji

emoji is a small, zero-dependency Python library that converts human-readable emoji shortcodes (:thumbs_up:) into their Unicode characters and back again. It implements the entire emoji set defined by the Unicode Consortium, plus a large set of common aliases, and ships built-in translations for 13 languages so shortcodes can be written in Spanish, Portuguese, Italian, French, German, Farsi, Indonesian, Simplified Chinese, Japanese, Korean, Russian, Arabic, and Turkish in addition to English.

Beyond simple text conversion, the library exposes lower-level primitives — analyze, emoji_list, distinct_emoji_list, emoji_count, replace_emoji, is_emoji, and purely_emoji — for scanning arbitrary strings, detecting emoji positions, counting occurrences, and stripping emoji from user input. Its tokenizer correctly distinguishes RGI (recommended-for-general-interchange) sequences from non-RGI combinations and gives callers explicit control over how zero-width-joiner (ZWJ) characters in compound emoji (like multi-person or skin-tone variants) are kept or discarded, so emojize(demojize(s)) == s round-trips can be preserved when needed.

The project has no runtime dependencies, ships a py.typed marker for full static-typing support, and its per-language emoji data is generated from the Unicode Consortium’s own tables rather than hand-maintained, keeping it accurate as new emoji are standardized.

What You Get

• emojize() / demojize() for converting shortcode text to Unicode emoji and back, in English or 12 other languages
• analyze() and emoji_list() for locating every emoji match in a string along with its start/end index and underlying Unicode data
• is_emoji() and purely_emoji() for validating whether a string is, or consists entirely of, emoji characters
• replace_emoji() and emoji_count() for stripping or counting emoji in user-generated text
• Explicit RGI vs non-RGI emoji distinction with configurable zero-width-joiner (ZWJ) handling for accurate round-tripping of compound emoji
• A py.typed marker and pyright/mypy-checked type hints for full static-typing support in editors and CI

Common Use Cases

• Rendering :shortcode:-style chat or markdown input (Slack/GitHub-style) into real Unicode emoji for display
• Sanitizing or stripping emoji out of user-submitted text before storage, search indexing, or NLP preprocessing
• Building multilingual chat, forum, or CMS input where users type emoji shortcodes in their own language
• Detecting and counting emoji usage in text analytics or content-moderation pipelines
• Converting emoji back to storable ASCII shortcode form for databases or APIs that reject non-ASCII text

Under The Hood

Architecture The package is organized as a small, flat pipeline: a data layer (emoji/unicode_codes/) holding per-language JSON tables generated offline from the Unicode Consortium’s own emoji charts via utils/generate_emoji.py; a tokenizer layer (emoji/tokenizer.py) that builds a search tree from that data and scans strings for RGI and non-RGI emoji sequences, including multi-codepoint ZWJ combinations; and a core API layer (emoji/core.py, re-exported through emoji/__init__.py) that wraps the tokenizer behind the public emojize/demojize/analyze/is_emoji/replace_emoji functions. This separation means the tokenizer’s matching logic can evolve — new emoji versions, new ZWJ edge cases — without touching the public API surface, and the data-generation step is fully decoupled from runtime code, run once per Unicode release rather than at import time.

Tech Stack emoji is pure Python 3.8+ with zero runtime dependencies, relying only on the standard library (re, unicodedata, typing). It’s packaged with setuptools via pyproject.toml, pulling its version dynamically from emoji.__version__, and bundles its language JSON files as package data. Development tooling includes pytest and coverage for testing, pyright (strict mode) and mypy for type-checking, typeguard for runtime type verification in tests, ruff for linting and formatting, and tox for testing across the full supported Python matrix.

Code Quality The test suite spans 11 files covering core conversion behavior, emoji-list analysis, dictionary/JSON data integrity, Unicode NFKC normalization, version compatibility, and ZWJ handling in all three configurable modes (common, keep, remove) — parametrized across every bundled language pack via shared test utilities. CI builds and inspects the actual published package (not just the source tree) and runs the test matrix against Python 3.8 through 3.14, including PyPy, verifying the wheel installs and behaves correctly across the full support range. Combined with strict pyright/mypy type-checking and ruff linting, this gives the library comprehensive, actively-enforced quality gates.

What Makes It Unique Most emoji libraries treat emoji as a flat name-to-character lookup table. emoji instead models the Unicode emoji specification’s distinction between RGI (recommended-for-general-interchange) sequences and non-RGI combinations, and exposes explicit, documented configuration for how zero-width-joiner characters in compound emoji — multi-person groups, skin-tone-modified emoji, flag sequences — are preserved or stripped. That precision lets callers guarantee lossless round-tripping (emojize(demojize(s)) == s) for compound emoji, a correctness detail that simpler shortcode-replacement libraries typically get wrong.