pycountry

26.2.16 verified Tue May 12 auth: no python install: verified quickstart: verified

pycountry is a Python library that provides access to various ISO standards databases, including ISO 3166 (countries and their subdivisions), ISO 639 (languages), ISO 4217 (currencies), and ISO 15924 (scripts). It acts as a pure wrapper around Debian's `pkg-isocodes` database, making this data accessible through a Python API, complete with translation files. The library is actively maintained, with data updates typically following the `pkg-isocodes` updates rather than a fixed release schedule. The current version is 26.2.16.

pip install pycountry

Common errors

error ModuleNotFoundError: No module named 'pycountry' ↓

cause The pycountry library has not been installed in the Python environment being used, or the environment where it's installed is not the one running the script.

fix

Ensure pycountry is installed using pip: pip install pycountry. If using a virtual environment, activate it before installing.

error KeyError: 'XX' (where 'XX' is a country code or name) ↓

cause This error occurs when attempting to retrieve a country, language, or other ISO standard entry using a key (like alpha_2, alpha_3, or name) that does not exist in the pycountry database for the given value, or when using an outdated key name (e.g., 'alpha2' instead of 'alpha_2').

fix

Use the get() method with a default fallback (e.g., pycountry.countries.get(alpha_2='XX', default=None)) or wrap the lookup in a try-except KeyError block. Verify that the key name is correct (e.g., alpha_2 for ISO 3166-1 alpha-2 codes).

error AttributeError: 'Country' object has no attribute 'common_name' ↓

cause This typically happens when trying to access an attribute (like 'common_name' or 'official_name') that might not exist for every single entry in the pycountry databases, or when using an outdated attribute name (e.g., 'alpha3' instead of 'alpha_3').

fix

Use getattr() with a default value (e.g., getattr(country, 'common_name', country.name)) or check for the attribute's existence using hasattr(country, 'common_name') before accessing it. Ensure you are using the correct, up-to-date attribute names (e.g., 'alpha_3' for alpha-3 codes).

error pkg_resource.DistributionNotFound: The 'pycountry' distribution was not found and is required by the application. ↓

cause When packaging a Python application with tools like PyInstaller or cx_Freeze, the metadata for `pycountry` is not automatically collected and bundled, leading to this error when the compiled executable tries to run.

fix

For PyInstaller, you need to explicitly include pycountry's metadata in the .spec file. Add from PyInstaller.utils.hooks import copy_metadata at the top and modify the datas array in the Analysis section to include datas=copy_metadata('pycountry'),.

Warnings

breaking In version 24.6.1, a fallback mechanism was removed. Previously, if `country.common_name` or `country.official_name` were unavailable, it would fall back to `country.name`. This fallback was reverted. Code relying on this implicit fallback will now raise `AttributeError` if the specific attribute is missing. ↓

fix Always check for attribute existence using `getattr(obj, 'attribute_name', default_value)` or handle `AttributeError` explicitly. Prefer `pycountry.countries.lookup()` for flexible name-based searches, which returns the most relevant match.

gotcha The data in pycountry is a direct wrapper around Debian's `pkg-isocodes` database. This means `pycountry` itself does not accept direct contributions for changes to country, language, or currency data. Any required changes to the underlying ISO data must be addressed with ISO or Debian's `pkg-isocodes` project. ↓

fix Understand that `pycountry` is a data consumer, not a data source for ISO standards. For political or data accuracy issues, upstream sources (ISO, Debian) should be consulted.

deprecated Support for Python 3.6 and 3.7 was officially dropped in version 23.12.11. ↓

fix Ensure your project runs on Python 3.8 or newer. The current `pycountry` version requires Python >=3.10.

gotcha When retrieving objects, using `.get()` requires an exact match on a specified attribute (e.g., `alpha_2`, `name`). If an attribute like `official_name` or `common_name` might not always exist for all entries, direct access (e.g., `country.official_name`) can raise an `AttributeError`. ↓

fix Use `getattr(obj, 'attribute_name', default_value)` to safely access potentially missing attributes, or implement `try-except AttributeError`. For searching, use `pycountry.collection.lookup('search_string')` as it provides a robust search across various naming attributes and handles unicode normalization.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.14s 40.5M

3.10 alpine (musl) - - 0.13s 40.5M

3.10 slim (glibc) wheel 1.8s 0.08s 41M

3.10 slim (glibc) - - 0.09s 41M

3.11 alpine (musl) wheel - 0.15s 42.3M

3.11 alpine (musl) - - 0.18s 42.3M

3.11 slim (glibc) wheel 1.8s 0.13s 43M

3.11 slim (glibc) - - 0.13s 43M

3.12 alpine (musl) wheel - 0.15s 34.2M

3.12 alpine (musl) - - 0.17s 34.2M

3.12 slim (glibc) wheel 1.8s 0.16s 35M

3.12 slim (glibc) - - 0.16s 35M

3.13 alpine (musl) wheel - 0.13s 33.9M

3.13 alpine (musl) - - 0.14s 33.8M

3.13 slim (glibc) wheel 1.7s 0.14s 34M

3.13 slim (glibc) - - 0.14s 34M

3.9 alpine (musl) wheel - 0.09s 35.6M

3.9 alpine (musl) - - 0.10s 35.6M

3.9 slim (glibc) wheel 2.0s 0.08s 36M

3.9 slim (glibc) - - 0.08s 36M

Imports

countries

import pycountry
country = pycountry.countries.get(alpha_2='US')

Provides access to ISO 3166-1 country data.

subdivisions

import pycountry
subdivision = pycountry.subdivisions.get(code='US-CA')

Provides access to ISO 3166-2 country subdivision data.

languages

import pycountry
language = pycountry.languages.get(alpha_3='eng')

Provides access to ISO 639-3 language data.

currencies

import pycountry
currency = pycountry.currencies.get(alpha_3='USD')

Provides access to ISO 4217 currency data.

scripts

import pycountry
script = pycountry.scripts.get(alpha_4='Latn')

Provides access to ISO 15924 script data.

historic_countries

import pycountry
historic_country = pycountry.historic_countries.get(alpha_3='SUN')

Provides access to ISO 3166-3 historic/deleted country data.

lookup
wrong
```
country = pycountry.countries.get(name='United States')
```
correct
```
import pycountry
country = pycountry.countries.lookup('United States')
```
'.get()' requires an exact match on a specific attribute. '.lookup()' provides a broader, more forgiving search across multiple attributes (name, common_name, official_name, codes).

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to retrieve country and language information using specific ISO codes and how to use the more flexible `lookup()` method for searching across different name attributes.

import pycountry

# Get a country by its Alpha-2 code
try:
    usa = pycountry.countries.get(alpha_2='US')
    print(f"Country Name: {usa.name}, Alpha-3: {usa.alpha_3}")
except KeyError:
    print("Country not found.")

# Get a language by its Alpha-3 code
try:
    english = pycountry.languages.get(alpha_3='eng')
    print(f"Language Name: {english.name}")
except KeyError:
    print("Language not found.")

# Search for a country using a more flexible lookup
try:
    bolivia_lookup = pycountry.countries.lookup('Bolivia')
    print(f"Lookup for Bolivia: {bolivia_lookup.name}, Official: {getattr(bolivia_lookup, 'official_name', 'N/A')}")
except LookupError:
    print("Bolivia not found via lookup.")