countrycodes is a dependency-free Python library for looking up all 249 ISO 3166-1 countries and territories, including a continent assignment for each.

Installation

pip install countrycodes

Requires Python 3.11 or newer.

Usage

from countrycodes import CountryNotFoundError, find_country, get_country, list_countries

united_states = get_country("us")
print(united_states.alpha3)  # USA
print(united_states.numeric)  # 840

united_kingdom = find_country("United Kingdom")
print(united_kingdom.alpha2)  # GB

print(len(list_countries()))  # 249

try:
    get_country("Atlantis")
except CountryNotFoundError:
    print("No matching country")

Lookups accept alpha-2, alpha-3, and numeric codes, as well as country names. Matching is case-insensitive and ignores surrounding or repeated whitespace. find_country returns None when there is no match; get_country raises CountryNotFoundError.

Data and licenses

The bundled country registry is an adapted subset of ISO 3166-1 data from the iso-codes project. Continent assignments are from GeoNames, using GeoNames' single-continent mapping for each country or territory. The registry data is licensed under LGPL-2.1-or-later, continent assignments under CC BY 4.0, and the library code under BSD 3-Clause. See the data notice, LGPL license text, and BSD license.