emoji-country-flag

What it is and what it does

emoji-country-flag is a lightweight utility for bidirectional conversion between flag emoji and their ASCII representations. It works by mapping ISO 3166 country codes (like `:US:` or `:GB:`) to pairs of Unicode regional indicator symbols, which browsers and phones render as flag emoji. The package provides three main operations: converting a code to an emoji, embedding emoji into text by replacing ASCII notation, and extracting ASCII notation back from emoji-containing text.

The package has no runtime dependencies and installs as a pure Python wheel. It supports current Python versions (3.10+) and is actively maintained. It's useful for applications that need to store or transmit flag representations in a portable text format, or for user interfaces that want to convert between human-readable country codes and visual emoji.

Use it for:

• Store country flags in databases or config files as portable `:XX:` codes instead of emoji characters.
• Convert user input containing flag emoji back to ASCII codes for processing or storage.
• Embed country flags into chat messages or text by replacing `:US:` with 🇺🇸 before display.
• Support subregion flags (e.g., `:gb-eng:` for England) in applications that need finer geographic granularity.
• Build text-based templates or markdown that render flags only when converted to emoji for display.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts between flag emoji and ASCII country codes (e.g., `:US:` ↔ 🇺🇸), and embeds flag emoji into text strings.

Yes. Low install friction, no dependencies, permissive MIT license, active maintenance, and no known vulnerabilities make this a safe choice. Install if you need bidirectional flag emoji–to–ASCII conversion; skip if your application doesn't work with country codes or emoji representation.

Install

emoji-country-flag on PyPI

pip install emoji-country-flag

uv add emoji-country-flag

poetry add emoji-country-flag

Installing emoji-country-flag

Before you install

Low friction: pure Python wheel with no runtime dependencies. Actively maintained as of 2026-07-30 with recent release (2025-09-21). Requires Python 3.10 or higher for current versions.

License in practice

MIT license (permissive) allows use in commercial and private projects with minimal restrictions—include a copy of the license and you're clear.

Quickstart

pip install emoji-country-flag

import flag

flag.flag("IL")  # Returns '🇮🇱'
flag.flagize("Flag of Israel :IL:")  # Returns 'Flag of Israel 🇮🇱'
flag.dflagize("Flag of Israel 🇮🇱")  # Returns 'Flag of Israel :IL:'

Requires Python 3.10 or higher; earlier Python versions (3.7–3.9) are limited to v1.3.2.

Verify before relying

• Whether all ISO 3166 country codes are supported or only a subset.
• Performance characteristics when processing large strings with many flag conversions.
• Behavior with unsupported country codes or malformed input.

Package facts

Evidence: emoji_country_flag-2.1.0-py3-none-any.whl

Tags

More Dynamic Content packages