pypi i demoji


Accurately find/replace/remove emojis in text strings

by Brad Solomon

1.1.0 (see all)License:Apache-2.0
pypi i demoji


Accurately find or remove emojis from a blob of text using data from the Unicode Consortium's emoji code repository.

License PyPI Status Python

Major Changes in Version 1.x

Version 1.x of demoji now bundles Unicode data in the package at install time rather than requiring a download of the codes from at runtime. Please see the for detail and be familiar with the changes before updating from 0.x to 1.x.

To report any regressions, please open a GitHub issue.

Basic Usage

demoji exports several text-related functions for find-and-replace functionality with emojis:

>>> tweet = """\
... #startspreadingthenews yankees win great start by ๐ŸŽ…๐Ÿพ going 5strong innings with 5kโ€™s๐Ÿ”ฅ ๐Ÿ‚
... solo homerun ๐ŸŒ‹๐ŸŒ‹ with 2 solo homeruns and๐Ÿ‘น 3run homerunโ€ฆ ๐Ÿคก ๐Ÿšฃ๐Ÿผ ๐Ÿ‘จ๐Ÿฝโ€โš–๏ธ with rbiโ€™s โ€ฆ ๐Ÿ”ฅ๐Ÿ”ฅ
... ๐Ÿ‡ฒ๐Ÿ‡ฝ and ๐Ÿ‡ณ๐Ÿ‡ฎ to close the game๐Ÿ”ฅ๐Ÿ”ฅ!!!โ€ฆ.
... WHAT A GAME!!..
... """
>>> demoji.findall(tweet)
    "๐Ÿ”ฅ": "fire",
    "๐ŸŒ‹": "volcano",
    "๐Ÿ‘จ๐Ÿฝ\u200dโš–๏ธ": "man judge: medium skin tone",
    "๐ŸŽ…๐Ÿพ": "Santa Claus: medium-dark skin tone",
    "๐Ÿ‡ฒ๐Ÿ‡ฝ": "flag: Mexico",
    "๐Ÿ‘น": "ogre",
    "๐Ÿคก": "clown face",
    "๐Ÿ‡ณ๐Ÿ‡ฎ": "flag: Nicaragua",
    "๐Ÿšฃ๐Ÿผ": "person rowing boat: medium-light skin tone",
    "๐Ÿ‚": "ox",

See below for function API.

Command-line Use

You can use demoji or python -m demoji to replace emojis in file(s) or stdin with their :code: equivalents:

$ cat out.txt
All done! โœจ ๐Ÿฐ โœจ
$ demoji out.txt
All done! :sparkles: :shortcake: :sparkles:

$ echo 'All done! โœจ ๐Ÿฐ โœจ' | demoji
All done! :sparkles: :shortcake: :sparkles:

$ demoji -
we didnt start the ๐Ÿ”ฅ
we didnt start the :fire:


findall(string: str) -> Dict[str, str]

Find emojis within string. Return a mapping of {emoji: description}.

findall_list(string: str, desc: bool = True) -> List[str]

Find emojis within string. Return a list (with possible duplicates).

If desc is True, the list contains description codes. If desc is False, the list contains emojis.

replace(string: str, repl: str = "") -> str

Replace emojis in string with repl.

replace_with_desc(string: str, sep: str = ":") -> str

Replace emojis in string with their description codes. The codes are surrounded by sep.

last_downloaded_timestamp() -> datetime.datetime

Show the timestamp of last download for the emoji data bundled with the package.

Footnote: Emoji Sequences

Numerous emojis that look like single Unicode characters are actually multi-character sequences. Examples:

  • The keycap 2๏ธโƒฃ is actually 3 characters, U+0032 (the ASCII digit 2), U+FE0F (variation selector), and U+20E3 (combining enclosing keycap).
  • The flag of Scotland 7 component characters, b'\\U0001f3f4\\U000e0067\\U000e0062\\U000e0073\\U000e0063\\U000e0074\\U000e007f' in full esaped notation.

(You can see any of these through s.encode("unicode-escape").)

demoji is careful to handle this and should find the full sequences rather than their incomplete subcomponents.

The way it does this it to sort emoji codes by their length, and then compile a concatenated regular expression that will greedily search for longer emojis first, falling back to shorter ones if not found. This is not by any means a super-optimized way of searching as it has O(N2) properties, but the focus is on accuracy and completeness.

>>> from pprint import pprint
>>> seq = """\
... I bet you didn't know that ๐Ÿ™‹, ๐Ÿ™‹โ€โ™‚๏ธ, and ๐Ÿ™‹โ€โ™€๏ธ are three different emojis.
... """
>>> pprint(seq.encode('unicode-escape'))  # Python 3
(b"I bet you didn't know that \\U0001f64b, \\U0001f64b\\u200d\\u2642\\ufe0f,"
 b' and \\U0001f64b\\u200d\\u2640\\ufe0f are three different emojis.\\n')



  • Add a __main.py__ to allow running python -m demoji; add an entry-point demoji command; permit stdin (-), file name(s), or piped stdin. Contribution by @jap.


This is a backwards-incompatible release with several substantial changes.

The largest change is that demoji now bundles a static copy of Unicode emoji data with the package at install time, rather than requiring a runtime download of the codes from

Changes below are grouped by their corresponding Semantic Versioning identifier.


  • Drop support for Python 2 and Python 3.5
  • The demoji package now bundles emoji data that is distributed with the package at install time, rather than requiring a download of the codes from the site at runtime (closes #23)
  • As a result of the above change, the following functions are removed from the demoji API:
    • download_codes()
    • parse_unicode_sequence()
    • parse_unicode_range()
    • stream_unicodeorg_emojifile()


  • The demoji.DIRECTORY and demoji.CACHEPATH attributes are deprecated due to no longer being functionally in used by the package. Accessing them will warn with a FutureWarning, and these attributes may be removed completely in a future release
  • demoji can now be installed with optional ujson support for faster loading of emoji data from file (versus the standard library's json, which is the default); use python -m pip install demoji[ujson]
  • The dependencies requests and colorama have been removed completely
  • importlib_resources (a backport module) is now required for Python < 3.7
  • The EMOJI_VERSION attribute, newly added to demoji, is a str denoting the Unicode database version in use


  • Fix a typo in demoji.__all__ to properly include demoji.findall_list()
  • Internal change: Functions that call set_emoji_pattern() are now decorated with a @cache_setter to set the cache
  • Some unit tests have been removed to update the change in behavior from downloading codes to bundling codes with install
  • Update README to reflect bundling behavior


  • Update emoji source list to version 13.1. (See 5090eb5.)
  • Formally support Python 3.9. (See 6e9c34c.)
  • Bugfix: ensure that demoji.last_downloaded_timestamp() returns correct UTC time. (See 6c8ad15.)


  • Feature: add findall_list() and replace_with_desc() functions. (See 7cea333.)
  • Modernize setup config to use setup.cfg. (See 8f141e7.)


  • Tox: formally add Python 3.8 tests.


  • Windows: use the colorama package to support printing ANSI escape sequences on Windows; this introduces colorama as a dependency. (See cd343c1.)
  • Setup: Fix a bug in that would require dependencies to be installed prior to installation of demoji in order to find the __version__. (See d5f429c.)
  • Python 2 + Windows support: use, encoding='utf-8') consistently in (See 1efec5d.)
  • Distribution: use a universal wheel in PyPI release. (See 8636a32.)


  • Performance improvement: use re.escape() rather than failing to compile a small subset of codes.
  • Remove an unused constant in

GitHub Stars



1yr ago








1yr ago
1yr ago
1yr ago
1yr ago
No alternatives found
No tutorials found
Add a tutorial