flag

Flag emoji for Python.

Converts flag emoji to ASCII and other way round.

This is based on http://schinckel.net/2015/10/29/unicode-flags-in-python/ by schinckel

Example

>>> import flag

>>> flag.flag("IL")
'🇮🇱'

>>> flag.flag("GBENG")
'🏴󠁧󠁢󠁥󠁮󠁧󠁿'

>>> flag.flagize("Flag of Israel :IL:")
'Flag of Israel 🇮🇱'

>>> flag.dflagize("Flag of Israel 🇮🇱")
'Flag of Israel :IL:'

>>> flag.flagize("England :gb-eng: is part of the UK :GB:", subregions=True)
'England 🏴󠁧󠁢󠁥󠁮󠁧󠁿 is part of the UK 🇬🇧'

>>> flag.dflagize("England 🏴󠁧󠁢󠁥󠁮󠁧󠁿 is part of the UK 🇬🇧", subregions=True)
'England :gb-eng: is part of the UK :GB:'

Install

pip install emoji-country-flag

See: https://pypi.org/project/emoji-country-flag/

Hint

If you don’t see the flags in your browser, try with your phone

https://flag.readthedocs.org

How it works

All the flag emoji are actually composed of two unicode letters. These are the 26 regional indicator symbols.

Alone they look like this: 🇦 🇧 🇨 🇩 🇪 🇫 🇬 🇭 🇮 🇯 🇰 🇱 🇲 🇳 🇴 🇵 🇶 🇷 🇸 🇹 🇺 🇻 🇼 🇽 🇾 🇿

If you pair them up according to ISO 3166 some browsers and phones will display a flag. For example TW is Taiwan: 🇹 + 🇼 = 🇹🇼

So, to encode an ASCII code like :TW: to 🇹🇼, we just need to convert the ASCII T and R to the corresponding regional indicator symbols 🇹 and 🇼. To reverse it, we translate the regional indicator symbols back to ASCII letters.

How do subregional flags work?

Functions

flag.flag(countrycode: str) → str[source]

Encodes a single flag to unicode. Two letters are converted to regional indicator symbols Three or more letters/digits are converted to tag sequences. Dashes, colons and other symbols are removed from input, only a-z, A-Z and 0-9 are processed.

In general a valid flag is either a two letter code from ISO 3166 (e.g. GB), a code from ISO 3166-2 (e.g. GBENG) or a numeric code from ISO 3166-1. However, not all codes produce valid unicode, see http://unicode.org/reports/tr51/#flag-emoji-tag-sequences for more information. From ISO 3166-2 only England gbeng, Scotland gbsct and Wales gbwls are considered RGI (recommended for general interchange) by the Unicode Consortium, see http://www.unicode.org/Public/emoji/latest/emoji-test.txt

Parameters:: countrycode (str) – Two letter ISO 3166 code or a regional code from ISO 3166-2.
Returns:: The unicode representation of the flag
Return type:: str

Encodes a single flag to unicode. Two letters are converted to regional indicator symbols Three or more letters/digits are converted to tag sequences. Dashes, colons and other symbols are removed from input, only a-z, A-Z and 0-9 are processed.

The unsupported and invalid parameter control which flags are converted. If a flag is not supported or invalid, the function will return the result of the on_illegal function or raise an error if either parameter is set to “error”.

Parameters:

countrycode (str) – Two letter ISO 3166 code or a regional code from ISO 3166-2.
unsupported (str|callable) –
“error” | “allow” | Callable(dict)

If “allow” return the flag. If “error” raise an error if flag is unsupported. If callable return the result of the callable if flag is unsupported. The callable receives the result of the flag.info() function e.g. {'id_status': 'regular', 'supported': False, 'valid': True}
invalid (str|callable) – Same as unsupported but for invalid flags
custom_data (dict) – Custom maps dict with custom valid/supported values to overwrite the standard values. For example with the WhatsApp Texas flag: {'XT': {'id_status': 'regular', 'supported': False, 'valid': True}}

Returns:

The unicode representation of the flag

Return type:

str

flag.flagize(text: str, subregions: bool = False) → str[source]

Encode flags. Replace all two letter codes :XX: with unicode flags (emoji flag sequences)

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision codes :xx-xxx: with unicode flags (flag emoji tag sequences).

Returns:

The text with all occurrences of :XX: replaced by unicode flags

Return type:

str

flag.dflagize(text: str, subregions: bool = False) → str[source]

Decode flags. Replace all unicode country flags (emoji flag sequences) in text with ascii two letter code :XX:

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision flags (flag emoji tag sequences) with :xx-xxx:

Returns:

The text with all unicode flags replaced by ascii sequence :XX:

Return type:

str

flag.flagize_subregional(text: str) → str[source]

Encode subregional/subdivision flags. Replace all regional codes :xx-xxx: with unicode flags (flag emoji tag sequences)

Parameters:: text (str) – The text
Returns:: The text with all occurrences of :xx-xxx: replaced by unicode flags
Return type:: str

flag.dflagize_subregional(text: str) → str[source]

Decode subregional/subdivision flags. Replace all unicode regional flags (flag emoji tag sequences) in text with their ascii code :xx-xxx:

Parameters:: text (str) – The text
Returns:: The text with all regional flags replaced by ascii sequence :xx-xxx:
Return type:: str

flag.info(countrycode: str, extended: bool = False) → MutableMapping[str, str | bool | None][source]: Retrieve information about a country code. E.g. {'id_status': 'regular', 'supported': False, 'valid': True}

flag.infos(extended: bool = False) → MutableMapping[str, MutableMapping[str, str | bool | None]][source]: Dict containing all supported and valid country codes. If extended is True, the dict will contain all country and subregional codes.

flag.version() → Mapping[Literal['module', 'cldr', 'emoji'], str][source]: Return the version of this module, the Unicode CLDR version of the data and the Unicode Emoji version of the validity data.

class flag.Flag(prefix_str: str = ':', suffix_str: str = ':', only_supported: bool = True, only_valid: bool = True, allow_subregions: bool = True, warn: bool = True)[source]

This class offers different prefix and suffix instead of colons and allows to only convert widely supported or valid flags.

__init__(prefix_str: str = ':', suffix_str: str = ':', only_supported: bool = True, only_valid: bool = True, allow_subregions: bool = True, warn: bool = True) → None[source]

Set a custom prefix and suffix. Instead of :XY: it will use {prefix}XY{suffix}.

To encode subregional flags, use a suffix that is either longer than 4 characters or that does not contain A-Z, a-z, 0-9 and does not start with a - (minus).

Parameters:

prefix_str (str) – The leading symbols
suffix_str (str) – The trailing symbols
only_supported (bool) – Only convert country codes that are widely supported by browsers and devices
only_valid (bool) – Only convert country codes that are considered “valid” by Unicode
allow_subregions (bool) – Also replace subregional/subdivision codes e.g. Scottland as :gb-sct:
warn (bool) – Show a warning if an unsafe prefix or suffix is used

add_flag(countrycode: str, supported: bool = True, valid: bool = True)[source]

Add a custom flag. This can be used to overwrite the standard values and allow custom flags to be considered supported and/or valid or remove supported flags. The current use-case for this function is the flag of Texas, which is only supported by WhatsApp. It is also possible to censor a flag. Example to add Texas flag: flag.add_flag("XT", supported=True, valid=True) Example to censor Italy flag: flag.add_flag("IT", supported=False, valid=False)

Parameters:

text (str) – The text
handle_illegal (callable) – See flag.flagize()

Returns:

The text with all regional flags replaced by ascii sequence {prefix}xx-xxx{suffix}

Return type:

str

dflagize(text: str, handle_illegal: Callable[[str, str], str] | None = None) → str[source]

Decode flags. Replace all unicode country flags (emoji flag sequences) in text with ascii two letter code {prefix}XX{suffix}

Depending on the settings, the function may only convert supported or valid flags. If an unsupported or invalid flag is found, the flag is either ignored or handle_illegal is called.

Parameters:

text (str) – The text
handle_illegal (callable) – A function that is called when an illegal flag is found. The function should take two arguments, the unicode flag and the code i.e. XY and return a string to replace the illegal flag.

Returns:

The text with all unicode flags replaced by ascii sequence {prefix}XX{suffix}

Return type:

str

dflagize_subregional(text: str, handle_illegal: Callable[[str, str], str] | None = None) → str[source]

Decode subregional/subdivision flags. Replace all unicode regional flags (flag emoji tag sequences) in text with their ascii code {prefix}xx-xxx{suffix}

Parameters:

text (str) – The text
handle_illegal (callable) – See flag.flagize()

Returns:

The text with all regional flags replaced by ascii sequence {prefix}xx-xxx{suffix}

Return type:

str

flagize(text: str, handle_illegal: Callable[[str, str], str] | None = None) → str[source]

Encode flags. Replace all two letter codes {prefix}XX{suffix} with unicode flags (emoji flag sequences)

For this method the suffix should not contain A-Z, a-z or 0-9 and not start with a - (minus).

Depending on the settings, the function may only convert supported or valid flags. If an unsupported or invalid flag is found, the flag is either ignored or handle_illegal is called.

Parameters:

text (str) – The text
handle_illegal (callable) – A function that is called when an illegal flag is found. The function should take two arguments, the match i.e. :XY: and the code i.e. XY and return a string to replace the illegal flag.

Returns:

The text with all occurrences of {prefix}XX{suffix} replaced by unicode flags

Return type:

str

flagize_subregional(text: str, handle_illegal: Callable[[str, str], str] | None = None) → str[source]

Encode subregional/subdivision flags. Replace all regional codes {prefix}xx-xxx{suffix} with unicode flags (flag emoji tag sequences)

For this method the suffix should not contain A-Z, a-z or 0-9 and not start with a - (minus).

Parameters:

text (str) – The text
handle_illegal (callable) – See flag.flagize()

Returns:

The text with all occurrences of {prefix}xx-xxx{suffix} replaced by unicode flags

Return type:

str

Supported emojis and patterns

Complete list can be found here.

The following flags are supported on all major platforms.

Code	Emoji
`:UN:`	🇺🇳
`:AC:`	🇦🇨
`:AD:`	🇦🇩
`:AE:`	🇦🇪
`:AF:`	🇦🇫
`:AG:`	🇦🇬
`:AI:`	🇦🇮
`:AL:`	🇦🇱
`:AM:`	🇦🇲
`:AO:`	🇦🇴
`:AQ:`	🇦🇶
`:AR:`	🇦🇷
`:AS:`	🇦🇸
`:AT:`	🇦🇹
`:AU:`	🇦🇺
`:AW:`	🇦🇼
`:AX:`	🇦🇽
`:AZ:`	🇦🇿
`:BA:`	🇧🇦
`:BB:`	🇧🇧
`:BD:`	🇧🇩
`:BE:`	🇧🇪
`:BF:`	🇧🇫
`:BG:`	🇧🇬
`:BH:`	🇧🇭
`:BI:`	🇧🇮
`:BJ:`	🇧🇯
`:BL:`	🇧🇱
`:BM:`	🇧🇲
`:BN:`	🇧🇳
`:BO:`	🇧🇴
`:BQ:`	🇧🇶
`:BR:`	🇧🇷
`:BS:`	🇧🇸
`:BT:`	🇧🇹
`:BV:`	🇧🇻
`:BW:`	🇧🇼
`:BY:`	🇧🇾
`:BZ:`	🇧🇿
`:CA:`	🇨🇦
`:CC:`	🇨🇨
`:CD:`	🇨🇩
`:CF:`	🇨🇫
`:CG:`	🇨🇬
`:CH:`	🇨🇭
`:CI:`	🇨🇮
`:CK:`	🇨🇰
`:CL:`	🇨🇱
`:CM:`	🇨🇲
`:CN:`	🇨🇳
`:CO:`	🇨🇴
`:CP:`	🇨🇵
`:CR:`	🇨🇷
`:CU:`	🇨🇺
`:CV:`	🇨🇻
`:CW:`	🇨🇼
`:CX:`	🇨🇽
`:CY:`	🇨🇾
`:CZ:`	🇨🇿
`:DE:`	🇩🇪
`:DG:`	🇩🇬
`:DJ:`	🇩🇯
`:DK:`	🇩🇰
`:DM:`	🇩🇲
`:DO:`	🇩🇴
`:DZ:`	🇩🇿
`:EA:`	🇪🇦
`:EC:`	🇪🇨
`:EE:`	🇪🇪
`:EG:`	🇪🇬
`:EH:`	🇪🇭
`:ER:`	🇪🇷
`:ES:`	🇪🇸
`:ET:`	🇪🇹
`:EU:`	🇪🇺
`:FI:`	🇫🇮
`:FJ:`	🇫🇯
`:FK:`	🇫🇰
`:FM:`	🇫🇲
`:FO:`	🇫🇴
`:FR:`	🇫🇷
`:GA:`	🇬🇦
`:GB:`	🇬🇧
`:GD:`	🇬🇩
`:GE:`	🇬🇪
`:GF:`	🇬🇫
`:GG:`	🇬🇬
`:GH:`	🇬🇭
`:GI:`	🇬🇮
`:GL:`	🇬🇱
`:GM:`	🇬🇲
`:GN:`	🇬🇳
`:GP:`	🇬🇵
`:GQ:`	🇬🇶
`:GR:`	🇬🇷
`:GS:`	🇬🇸
`:GT:`	🇬🇹
`:GU:`	🇬🇺
`:GW:`	🇬🇼
`:GY:`	🇬🇾
`:HK:`	🇭🇰
`:HM:`	🇭🇲
`:HN:`	🇭🇳
`:HR:`	🇭🇷
`:HT:`	🇭🇹
`:HU:`	🇭🇺
`:IC:`	🇮🇨
`:ID:`	🇮🇩
`:IE:`	🇮🇪
`:IL:`	🇮🇱
`:IM:`	🇮🇲
`:IN:`	🇮🇳
`:IO:`	🇮🇴
`:IQ:`	🇮🇶
`:IR:`	🇮🇷
`:IS:`	🇮🇸
`:IT:`	🇮🇹
`:JE:`	🇯🇪
`:JM:`	🇯🇲
`:JO:`	🇯🇴
`:JP:`	🇯🇵
`:KE:`	🇰🇪
`:KG:`	🇰🇬
`:KH:`	🇰🇭
`:KI:`	🇰🇮
`:KM:`	🇰🇲
`:KN:`	🇰🇳
`:KP:`	🇰🇵
`:KR:`	🇰🇷
`:KW:`	🇰🇼
`:KY:`	🇰🇾
`:KZ:`	🇰🇿
`:LA:`	🇱🇦
`:LB:`	🇱🇧
`:LC:`	🇱🇨
`:LI:`	🇱🇮
`:LK:`	🇱🇰
`:LR:`	🇱🇷
`:LS:`	🇱🇸
`:LT:`	🇱🇹
`:LU:`	🇱🇺
`:LV:`	🇱🇻
`:LY:`	🇱🇾
`:MA:`	🇲🇦
`:MC:`	🇲🇨
`:MD:`	🇲🇩
`:ME:`	🇲🇪
`:MF:`	🇲🇫
`:MG:`	🇲🇬
`:MH:`	🇲🇭
`:MK:`	🇲🇰
`:ML:`	🇲🇱
`:MM:`	🇲🇲
`:MN:`	🇲🇳
`:MO:`	🇲🇴
`:MP:`	🇲🇵
`:MQ:`	🇲🇶
`:MR:`	🇲🇷
`:MS:`	🇲🇸
`:MT:`	🇲🇹
`:MU:`	🇲🇺
`:MV:`	🇲🇻
`:MW:`	🇲🇼
`:MX:`	🇲🇽
`:MY:`	🇲🇾
`:MZ:`	🇲🇿
`:NA:`	🇳🇦
`:NC:`	🇳🇨
`:NE:`	🇳🇪
`:NF:`	🇳🇫
`:NG:`	🇳🇬
`:NI:`	🇳🇮
`:NL:`	🇳🇱
`:NO:`	🇳🇴
`:NP:`	🇳🇵
`:NR:`	🇳🇷
`:NU:`	🇳🇺
`:NZ:`	🇳🇿
`:OM:`	🇴🇲
`:PA:`	🇵🇦
`:PE:`	🇵🇪
`:PF:`	🇵🇫
`:PG:`	🇵🇬
`:PH:`	🇵🇭
`:PK:`	🇵🇰
`:PL:`	🇵🇱
`:PM:`	🇵🇲
`:PN:`	🇵🇳
`:PR:`	🇵🇷
`:PS:`	🇵🇸
`:PT:`	🇵🇹
`:PW:`	🇵🇼
`:PY:`	🇵🇾
`:QA:`	🇶🇦
`:RE:`	🇷🇪
`:RO:`	🇷🇴
`:RS:`	🇷🇸
`:RU:`	🇷🇺
`:RW:`	🇷🇼
`:SA:`	🇸🇦
`:SB:`	🇸🇧
`:SC:`	🇸🇨
`:SD:`	🇸🇩
`:SE:`	🇸🇪
`:SG:`	🇸🇬
`:SH:`	🇸🇭
`:SI:`	🇸🇮
`:SJ:`	🇸🇯
`:SK:`	🇸🇰
`:SL:`	🇸🇱
`:SM:`	🇸🇲
`:SN:`	🇸🇳
`:SO:`	🇸🇴
`:SR:`	🇸🇷
`:SS:`	🇸🇸
`:ST:`	🇸🇹
`:SV:`	🇸🇻
`:SX:`	🇸🇽
`:SY:`	🇸🇾
`:SZ:`	🇸🇿
`:TA:`	🇹🇦
`:TC:`	🇹🇨
`:TD:`	🇹🇩
`:TF:`	🇹🇫
`:TG:`	🇹🇬
`:TH:`	🇹🇭
`:TJ:`	🇹🇯
`:TK:`	🇹🇰
`:TL:`	🇹🇱
`:TM:`	🇹🇲
`:TN:`	🇹🇳
`:TO:`	🇹🇴
`:TR:`	🇹🇷
`:TT:`	🇹🇹
`:TV:`	🇹🇻
`:TW:`	🇹🇼
`:TZ:`	🇹🇿
`:UA:`	🇺🇦
`:UG:`	🇺🇬
`:UM:`	🇺🇲
`:US:`	🇺🇸
`:UY:`	🇺🇾
`:UZ:`	🇺🇿
`:VA:`	🇻🇦
`:VC:`	🇻🇨
`:VE:`	🇻🇪
`:VG:`	🇻🇬
`:VI:`	🇻🇮
`:VN:`	🇻🇳
`:VU:`	🇻🇺
`:WF:`	🇼🇫
`:WS:`	🇼🇸
`:XK:`	🇽🇰
`:YE:`	🇾🇪
`:YT:`	🇾🇹
`:ZA:`	🇿🇦
`:ZM:`	🇿🇲
`:ZW:`	🇿🇼

Subregional flags

The only widely supported subregional flags are currently: England, Scotland and Wales (as of iOS 17 and Android 14).

Code	Emoji
`:gb-sct:`	🏴󠁧󠁢󠁳󠁣󠁴󠁿
`:gb-wls:`	🏴󠁧󠁢󠁷󠁬󠁳󠁿
`:gb-eng:`	🏴󠁧󠁢󠁥󠁮󠁧󠁿
`:us-tx:`	🏴󠁵󠁳󠁴󠁸󠁿

WhatsApp offers one other state flag: Texas.
If you use WhatsApp’s emoji panel to select the Texas flag, WhatsApp uses 🇽🇹 i.e. flagize(“:XT:”) for Texas. This code “XT” is specified by Unicode as “excluded” meaning it is explicitly for private use and can be defined by anyone. Therefore, it is likely not displayed as the Texas flag on other platforms.
But WhatsApp also recognizes the flag emoji tag sequence flagize(“:us-tx:”, subregions=True) and displays the same flag.

How subregional flags work

They work very similar to the country flags. The ASCII codes are transformed by replacing them with specific codepoints that are called “tags”.

The basic format for a tag flag is:

black_flag_emoji followed by region_code_in_tag followed by cancel_tag

Note

black_flag_emoji:

U+1F3F4 ( 🏴 )

cancel_tag:

U+E007F (invisible, signifies the end of the flag code)

region_code_in_tag:

It is formed using the abbreviation defined in ISO 3166-2 and adding 0xE0000 to every ASCII value of the code. For example England is GB-ENG.

A full list of valid codes can be found here: github.com/unicode-org/…/subdivisions/en.xml

It’s also possible to use a 3-digit-code from github.com/unicode-org/…/UnMacroRegions.txt

Example:

England is GB-ENG in ISO 3166-2.
We drop the hyphen and make it lowercase to get gbeng.
To transform this to “tags”, we need to add the value 0xE0000 = 917504 to every unicode value of gbeng:

g is unicode 0x67 or decimal 103, so 103 + 917504 = 917607 or 0xE0067
b is 0x62 and becomes 0xE0062
e is 0x65 and becomes 0xE0065
n is 0x6E and becomes 0xE006E
g is 0x67 and becomes 0xE0067

Together it’s:

                      g        b        e        n        g
ASCII:                0x67     0x62     0x65     0x6E     0x67
Tags:   0x1F3F4    0xE0067  0xE0062  0xE0065  0xE006E  0xE0067  0xE007F
        black_flag                                             cancel_tag

Unlike the regional indicator symbols, tags are not rendered on incompatible system, they will simply be invisible and have no width. So, if the particular flag is not supported or if tag flags are not supported at all, the only visible character will be a black flag.

Validity and Support

Unicode publishes a listing of all country codes and subregional codes that are available. The data can be found in the CLDR downloads or in the repository at https://github.com/unicode-org/cldr/blob/release-45/common/validity/region.xml

The module offers this data as a dictionary (roughly 6000 country codes):

import flag

# For a single country code:
flag.info("US")
# {'id_status': 'regular', 'supported': True, 'valid': True}

# List of all country codes
flag.infos(extended=True)
# {'US': {'id_status': 'regular', 'supported': True, 'valid': True}, {'IT': {...}, ...}

The validity (dict-key 'valid') is specified in the Unicode Emoji reports: https://www.unicode.org/reports/tr51/#Flags

The module also offers information about the support of the flags (dict-key 'supported'). This data is based on visual inspection on major devices and platforms.

Platforms with full-support are macOS 14, iOS 17, Android 14, Firefox 127, Telegram 10, WhatsApp 2.20.

The data disregards Windows as it does not support any flags by default. Some third-party Windows apps like Firefox or Telegram do support flags.

Also it is disregarded that the People’s Republic of China censors some flags on some devices or on some language/region settings.

You can view the complete list of flags at here.

Unsupported flags:

An Android, Firefox, WhatsApp and Telegram: unsupported two-letter flags are generally displayed as two (white on blue) letters, subregional flags are displayed as black flags.

On Windows two-letter codes are displayed as the letters themselves, subregional codes are displayed as a black flag.

On iOS and macOS unsupported two-letter flags are displayed as two letters with a black rectangle areound the letters, subregional codes are displayed similarly or as a black flag.

Example:

import flag

my_flags = flag.Flag(only_supported=True, only_valid=True, allow_subregions=True)
print(my_flags.flagize("Flag of the United States :US:"))
# This will show the US flag instead of :US:

print(my_flags.flagize("A invalid flag :XT:"))  # :XT: is kept, as it is not supported

my_flags.flag("XY")  # TRaise an error, because XY is not a valid country code

# Add the custom code XT, which is used for the Texas flag by WhatsApp
# And also the standard code US-TX which is understood by WhatsApp (but not generated)
my_flags.add_flag("XT")
my_flags.add_flag("US-TX")

# This will show the Texas flag on WhatsApp
# On other platforms, the first will show the letters 🇽🇹, the second an emmpty flag 🏴󠁵󠁳󠁴󠁸󠁿
print(my_flags.flagize("The Texas flag :XT:")) p
print(my_flags.flagize("The Texas flag :us-tx:"))

flag

Example

Install

How it works

Functions

Supported emojis and patterns

Subregional flags

How subregional flags work

Example:

Validity and Support

Unsupported flags:

Example:

Indices and tables