emojifyi 0.2.1

Pure Python emoji toolkit -- encoding, lookup, search, CLI, MCP server, and API client for 3,781 emojis from Unicode Emoji 16.0.

emojifyi

Pure Python emoji toolkit for developers. Encode any emoji into 8 representations, look up metadata for 3,781 emojis, search and browse by category -- all with zero dependencies. Includes a CLI, MCP server for AI assistants, and an API client for emojifyi.com.

Browse all emojis at emojifyi.com -- search emojis, browse categories, emoji encoding tools, emoji collections

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Emoji Encoding
  • Emoji Lookup & Search
  • Browse by Category
• Advanced Usage
• CLI
• MCP Server
• API Client
• API Reference
  • Encoding
  • Lookup and Search
  • Browse
• Data Types
• Features
• Learn More About Emoji
• FYIPedia Developer Tools
• License

Install

pip install emojifyi            # Core library (zero dependencies)
pip install emojifyi[cli]       # + CLI (typer, rich)
pip install emojifyi[mcp]       # + MCP server for AI assistants
pip install emojifyi[api]       # + HTTP client for emojifyi.com API
pip install emojifyi[all]       # Everything

Quick Start

from emojifyi import encode, get_emoji, search

# Encode any emoji into 8 representations
result = encode("\U0001f600")
print(result.codepoint)         # U+1F600
print(result.utf8_bytes)        # 0xF0 0x9F 0x98 0x80
print(result.html_entity)       # 😀
print(result.css_content)       # \1F600
print(result.python_literal)    # \U0001F600
print(result.java_literal)      # \uD83D\uDE00

# Look up emoji metadata
info = get_emoji("red-heart")
print(info.character)           # Red heart emoji
print(info.category)            # smileys-and-emotion
print(info.emoji_version)       # 1.0

# Search emojis by name
for emoji in search("fire")[:5]:
    print(f"{emoji.character} {emoji.cldr_name}")

What You Can Do

Emoji Encoding

Every emoji can be represented in multiple encoding formats depending on the platform and programming language. The Unicode Consortium defines codepoints, but developers need UTF-8 bytes for web servers, HTML entities for markup, CSS content values for pseudo-elements, and language-specific escape sequences for source code. The encode() function computes all 8 representations in a single call.

Format	Example (U+1F600)	Use Case
Codepoint	U+1F600	Unicode documentation, character charts
UTF-8 Bytes	0xF0 0x9F 0x98 0x80	Web servers, file encoding, network protocols
UTF-16 Surrogates	0xD83D 0xDE00	JavaScript internals, Java strings, Windows APIs
HTML Entity	😀	HTML documents, email templates
CSS Content	\1F600	CSS content property, pseudo-elements
Python Literal	\U0001F600	Python source code, string escapes
JavaScript Literal	\u{1F600}	ES6+ JavaScript/TypeScript source code
Java Literal	\uD83D\uDE00	Java source code (surrogate pairs)

from emojifyi import encode

# Convert any emoji to all 8 encoding formats at once
result = encode("\U0001f525")
print(result.codepoint)         # U+1F525
print(result.utf8_bytes)        # 0xF0 0x9F 0x94 0xA5
print(result.html_entity)       # 🔥
print(result.css_content)       # \1F525
print(result.javascript_literal) # \u{1F525}
print(result.java_literal)      # \uD83D\uDD25

Learn more: Emoji Unicode Lookup Tool · Emoji Encoding Converter

Emoji Lookup & Search

The package includes a complete dataset of 3,781 emojis from Unicode Emoji 16.0 with rich metadata for each entry: CLDR short name, category, subcategory, emoji version, unicode version, year added, and type classification. Zero-Width Joiner (ZWJ) sequences -- where multiple codepoints combine into a single visible emoji like family or profession emojis -- are fully supported with the is_zwj flag. Skin tone modifiers are tracked via has_skin_tones.

from emojifyi import get_emoji, get_emoji_by_char, search

# Look up emoji metadata by slug identifier
info = get_emoji("red-heart")
print(info.character)       # (red heart emoji)
print(info.cldr_name)       # red heart
print(info.category)        # smileys-and-emotion
print(info.emoji_version)   # 1.0
print(info.is_zwj)          # False

# Look up by the emoji character itself
fire = get_emoji_by_char("\U0001f525")
print(fire.slug)            # fire
print(fire.added_year)      # 2010

# Search emojis by name with natural language queries
for emoji in search("heart")[:5]:
    print(f"{emoji.character} {emoji.cldr_name} (v{emoji.emoji_version})")

Learn more: Emoji Search Engine · Browse Emoji Categories

Browse by Category

The Unicode Consortium organizes all 3,781 emojis into 10 top-level categories and 100 subcategories. Each category groups semantically related emojis -- from facial expressions and hand gestures to flags, food, and travel symbols. You can also filter by emoji version to discover which emojis were added in each Unicode release.

Category	Slug	Emojis	Description
Smileys & Emotion	smileys-and-emotion	184	Facial expressions, hearts, hand gestures
People & Body	people-and-body	393	People, professions, body parts, skin tones
Animals & Nature	animals-and-nature	151	Animals, plants, weather, earth
Food & Drink	food-and-drink	134	Fruits, meals, beverages, utensils
Travel & Places	travel-and-places	264	Vehicles, buildings, maps, sky
Activities	activities	82	Sports, arts, games, celebrations
Objects	objects	299	Tools, clothing, music, office supplies
Symbols	symbols	224	Arrows, math, zodiac, geometric shapes
Flags	flags	275	Country flags, regional flags, flag symbols
Component	component	9	Skin tone modifiers, hair components

from emojifyi import by_category, by_version, categories, emoji_count

# Browse all emojis in the food and drink category
food = by_category("food-and-drink")
print(f"{len(food)} food & drink emojis")

# Discover new emojis added in Unicode Emoji 16.0
new_emojis = by_version("16.0")
for e in new_emojis[:5]:
    print(f"{e.character} {e.cldr_name}")

# List all 10 top-level emoji categories
for cat in categories():
    print(f"{cat.icon} {cat.name}")

# Total emoji count in the dataset
print(f"Total: {emoji_count()} emojis")  # 3781

Learn more: Browse Emoji Categories · Emoji Versions & Release History

Advanced Usage

from emojifyi import (
    get_emoji_by_char, by_category, by_version,
    categories, subcategories, all_emojis, emoji_count,
)

# Look up by character
info = get_emoji_by_char("\U0001f525")
print(info.slug)  # fire

# Browse by category
animals = by_category("animals-and-nature")
print(len(animals))  # 151 emojis

# New emojis in a specific version
new = by_version("16.0")
print(len(new))  # Latest additions

# Category metadata
for cat in categories():
    print(f"{cat.icon} {cat.name} ({cat.slug})")

# Total count
print(emoji_count())  # 3781

CLI

Requires the cli extra: pip install emojifyi[cli]

# Look up emoji by slug
emojifyi lookup grinning-face

# Look up by character
emojifyi char "\U0001f600"

# Search emojis
emojifyi search heart
emojifyi search fire --limit 5

# Show all 8 encodings
emojifyi encode "\U0001f600"

# List categories
emojifyi categories

# Browse a category
emojifyi browse smileys-and-emotion

# Dataset statistics
emojifyi stats

MCP Server

Requires the mcp extra: pip install emojifyi[mcp]

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "emojifyi": {
            "command": "python",
            "args": ["-m", "emojifyi.mcp_server"]
        }
    }
}

Available tools:

Tool	Description
emoji_lookup	Look up emoji by slug or character
emoji_search	Search emojis by name
emoji_encode	Encode emoji into 8 representations
emoji_categories	List all 10 categories
emoji_by_category	Browse emojis in a category
emoji_stats	Dataset statistics

API Client

Requires the api extra: pip install emojifyi[api]

from emojifyi.api import EmojiFYI

with EmojiFYI() as api:
    # Get emoji details
    info = api.emoji("grinning-face")
    print(info["character"])

    # Search emojis
    results = api.search("heart")
    for r in results["results"]:
        print(r["character"], r["cldr_name"])

    # List categories
    cats = api.categories()
    print(cats["count"])  # 10

    # Get random emoji
    lucky = api.random()
    print(lucky["character"], lucky["cldr_name"])

Full API documentation at emojifyi.com/developers.

API Reference

Encoding

Function	Description
encode(char) -> EncodingResult	All 8 encodings at once
char_to_codepoint(char) -> str	Character to U+XXXX
encode_utf8(char) -> str	UTF-8 byte representation
encode_utf16(char) -> str	UTF-16 surrogates
encode_html(codepoint) -> str	HTML numeric entity
encode_css(codepoint) -> str	CSS content value
encode_python(codepoint) -> str	Python literal
encode_javascript(codepoint) -> str	JavaScript literal
encode_java(char) -> str	Java literal (with surrogates)

Lookup and Search

Function	Description
get_emoji(slug) -> EmojiInfo | None	Look up by slug
get_emoji_by_char(char) -> EmojiInfo | None	Look up by character
search(query, limit=20) -> list[EmojiInfo]	Case-insensitive name search
all_emojis() -> list[EmojiInfo]	All 3,781 emojis
emoji_count() -> int	Total emoji count

Browse

Function	Description
by_category(slug) -> list[EmojiInfo]	Filter by category
by_version(version) -> list[EmojiInfo]	Filter by emoji version
categories() -> list[Category]	All 10 categories
subcategories(slug?) -> list[Subcategory]	All or filtered subcategories

Data Types

• EncodingResult -- 8-field NamedTuple: codepoint, utf8_bytes, utf16_surrogates, html_entity, css_content, python_literal, javascript_literal, java_literal
• EmojiInfo -- 12-field NamedTuple: character, slug, cldr_name, codepoint, category, subcategory, emoji_version, unicode_version, added_year, emoji_type, is_zwj, has_skin_tones
• Category -- 4-field NamedTuple: slug, name, icon, order
• Subcategory -- 4-field NamedTuple: slug, name, category_slug, order

Features

• 8 encoding types: UTF-8 bytes, UTF-16 surrogates, HTML entity, CSS content, Python/JavaScript/Java literals, codepoint
• 3,781 emojis: Full Unicode Emoji 16.0 dataset with metadata
• 10 categories, 100 subcategories: Browse and filter
• ZWJ support: Multi-codepoint sequences, flags, keycaps, skin tones
• Zero dependencies: Core library is pure Python with bundled JSON data
• CLI: Rich terminal interface for emoji lookup, search, and encoding
• MCP server: AI assistant integration with 6 tools
• API client: HTTP client for emojifyi.com REST API
• Type-safe: Full type annotations, py.typed marker (PEP 561)

Learn More About Emoji

• Browse: Emoji Browser · Search Emojis · Categories
• Tools: Unicode Lookup · Encoding Tool
• Collections: Emoji Collections · Versions
• API: REST API Docs · OpenAPI Spec

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies -- colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,781 emojis -- emojifyi.com
symbolfyi	PyPI	npm	Symbol encoding in 11 formats -- symbolfyi.com
unicodefyi	PyPI	npm	Unicode lookup with 17 encodings -- unicodefyi.com
fontfyi	PyPI	npm	Google Fonts metadata & CSS -- fontfyi.com
distancefyi	PyPI	npm	Haversine distance & travel times -- distancefyi.com
timefyi	PyPI	npm	Timezone ops & business hours -- timefyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements -- namefyi.com
unitfyi	PyPI	npm	Unit conversion, 220 units -- unitfyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation -- holidayfyi.com
cocktailfyi	PyPI	--	Cocktail ABV, calories, flavor -- cocktailfyi.com
fyipedia	PyPI	--	Unified CLI: fyi color info FF6B35 -- fyipedia.com
fyipedia-mcp	PyPI	--	Unified MCP hub for AI assistants -- fyipedia.com

License

MIT