---
id: emoji-country-flag
version: "2.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# emoji-country-flag — En/Decode unicode country flags emoji

License: permissive · Maintenance: active · Downloads: 93.0K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 93.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

flag emoji conversion, country code to emoji, ascii flag notation, emoji text replacement, unicode regional indicators, flag emoji encoding, country flag symbols, emoji, internationalization, text-processing

[View on SkillFed](https://skillfed.io/packages/emoji-country-flag) · [View on PyPI](https://pypi.org/project/emoji-country-flag/)