{"id":2077,"library":"iso3166","title":"ISO 3166-1 Country Definitions","description":"`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.","status":"active","version":"2.1.1","language":"python","source_language":"en","source_url":"http://github.com/deactivated/python-iso3166","tags":["iso","country codes","i18n","standardization"],"install":[{"cmd":"pip install iso3166","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The 'countries' lookup object is directly exposed for convenience. While 'import iso3166' works, accessing 'iso3166.countries' is less common than direct import.","wrong":"import iso3166; countries = iso3166.countries","symbol":"countries","correct":"from iso3166 import countries"}],"quickstart":{"code":"from iso3166 import countries\n\n# Get a country by its alpha-2 code\nus = countries.get('US')\nprint(f\"Alpha-2: {us.alpha2}, Name: {us.name}, Alpha-3: {us.alpha3}, Numeric: {us.numeric}\")\n\n# Get a country by its alpha-3 code\njapan = countries.get('JPN')\nprint(f\"Alpha-2: {japan.alpha2}, Name: {japan.name}\")\n\n# Iterate through all countries\nfor country in countries:\n    if country.numeric == '036': # Australia\n        print(f\"Found country by numeric code: {country.name}\")\n        break","lang":"python","description":"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."},"warnings":[{"fix":"If you need subdivision data, install `iso3166-2` (`pip install iso3166-2`). If you only need top-level country codes, `iso3166` is correct.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'-1':3,20,66 '-2':31 '-3':36 '2.1.1':49 '2022':53 '3166':2,19,65 'allow':24 'alpha':30,35 'chang':61 'code':22,41,70 'contain':15 'convers':25 'countri':4,21,43,69 'current':46 'definit':5,16 'digit':39 'i18n':71 'incorpor':60 'iso':1,18,64,68 'iso3166':6 'juli':52 'letter':29,34 'librari':11 'lightweight':9 'made':58 'name':44 'numer':40 'provid':12 'python':10 'releas':50 'self':14 'self-contain':13 'standard':67,72 'three':33,38 'three-digit':37 'three-lett':32 'two':28 'two-lett':27 'typic':57 'updat':55 'version':47","created_at":"2026-04-09T18:42:32.657896+00:00","updated_at":"2026-04-16T15:48:23.573308+00:00","problems":[{"fix":"Install the library using pip: `pip install iso3166`. If using an IDE like PyCharm, ensure the correct Python interpreter where the package is installed is selected for the project.","cause":"The 'iso3166' library is not installed in the Python environment being used, or the Python interpreter configured for the project/IDE does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'iso3166'"},{"fix":"Try reinstalling the package: `pip uninstall iso3166 && pip install iso3166`. If in an IDE, restarting the IDE or clearing its cache might help. Verify the import statement `from iso3166 import countries` is correct according to the documentation.","cause":"This typically occurs when the 'iso3166' package is either not correctly installed, corrupted, or there's an environment issue where Python cannot properly resolve the 'countries' object from the module. Sometimes it can be a caching issue in an IDE.","error":"ImportError: cannot import name 'countries' from 'iso3166'"},{"fix":"Ensure the country code or name is valid according to the ISO 3166-1 standard. To handle missing entries gracefully, use the `.get()` method with a default value, for example: `country = countries.get('XX', None)` or `country = countries.get('XX', 'Unknown Country')`.","cause":"You are attempting to access a country using a code (e.g., 'XX' for alpha-2) or name that does not exist in the `iso3166` dataset when using direct dictionary-style lookup (e.g., `countries['XX']`).","error":"KeyError: 'XX'"},{"fix":"Always check if the result from `countries.get()` is not `None` before attempting to access its attributes. For example:\n```python\nfrom iso3166 import countries\n\ncountry_code = 'ZZ'\ncountry = countries.get(country_code)\n\nif country:\n    print(country.name)\nelse:\n    print(f'Country with code {country_code} not found.')\n```","cause":"This error occurs when you use `iso3166.countries.get()` to retrieve a country using a non-existent code, which returns `None`, and then you immediately try to access an attribute (like `.name` or `.alpha2`) on that `None` object.","error":"AttributeError: 'NoneType' object has no attribute 'name'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/deactivated/python-iso3166","docs":null,"changelog":null,"pypi":"https://pypi.org/project/iso3166/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}