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

• pip install pycountry Install stable version

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

  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

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.")