ISO 3166-1 Country Definitions

2.1.1 · active · verified Thu Apr 09

`iso3166` is a lightweight Python library providing self-contained definitions for ISO 3166-1 country codes. It allows conversion between two-letter (alpha-2), three-letter (alpha-3), three-digit (numeric) codes, and country names. The current version is 2.1.1, released in July 2022, and updates are typically made to incorporate changes in the ISO 3166-1 standard.

Warnings

gotcha This library (`iso3166`) *only* provides ISO 3166-1 country codes (e.g., 'US', 'USA'). It does not include ISO 3166-2 country subdivisions (e.g., states, provinces, regions). For subdivision data, consider libraries like `iso3166-2` which is a separate package.
Fix: If you need subdivision data, install `iso3166-2` (`pip install iso3166-2`). If you only need top-level country codes, `iso3166` is correct.
gotcha Users sometimes encounter `ImportError: cannot import name 'countries' from 'iso3166'`. This can be due to environment issues, incorrect package installation, or cached interpreter states (e.g., in Jupyter notebooks).
Fix: Try updating the package (`pip install --upgrade iso3166`), uninstalling and reinstalling it, or restarting your Python kernel/environment. Manual deletion of residual package files might also be necessary in some cases.
gotcha The official GitHub repository (`deactivated/python-iso3166`) is marked as 'deactivated'. While the PyPI package still receives updates (primarily for ISO data changes) and is functional, the repository status might suggest less active new feature development or community interaction compared to other actively maintained projects.
Fix: Be aware that major new features or significant code changes are less likely from the original maintainer. The library remains suitable for its core purpose of ISO 3166-1 data lookup.

Install

pip install iso3166 Install stable version

Imports

countries
```
from iso3166 import countries
```
The 'countries' lookup object is directly exposed for convenience. While 'import iso3166' works, accessing 'iso3166.countries' is less common than direct import.

Quickstart

This quickstart demonstrates how to import the `countries` object and retrieve country data using various ISO 3166-1 codes (alpha-2, alpha-3, numeric) or iterate through the entire list. Each country object provides `name`, `alpha2`, `alpha3`, and `numeric` attributes.

from iso3166 import countries

# Get a country by its alpha-2 code
us = countries.get('US')
print(f"Alpha-2: {us.alpha2}, Name: {us.name}, Alpha-3: {us.alpha3}, Numeric: {us.numeric}")

# Get a country by its alpha-3 code
japan = countries.get('JPN')
print(f"Alpha-2: {japan.alpha2}, Name: {japan.name}")

# Iterate through all countries
for country in countries:
    if country.numeric == '036': # Australia
        print(f"Found country by numeric code: {country.name}")
        break

view raw JSON →