iso3166

library2.1.1pypypi✓ verified 23d ago

`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.

data

pip install iso3166

github ↗package ↗

INSTALL

IMPORT

SIG · ISO3166

iso3166

datapythonv2.1.1

Install

1.6s avg

Import

14ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.014s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.014s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

countries

✓ from iso3166 import countries

✗ import iso3166; countries = iso3166.countries

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

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

Debug

Known issues

gotchaThis 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.

affects: All versions

gotchaUsers 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.

affects: All versions

gotchaThe 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'iso3166'

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.

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.

ImportError: cannot import name 'countries' from 'iso3166'

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.

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.

KeyError: 'XX'

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']`).

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')`.

AttributeError: 'NoneType' object has no attribute 'name'

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.

fix

Always check if the result from `countries.get()` is not `None` before attempting to access its attributes. For example:
```python
from iso3166 import countries

country_code = 'ZZ'
country = countries.get(country_code)

if country:
    print(country.name)
else:
    print(f'Country with code {country_code} not found.')
```

Upgrade

Version history

2.1.1latest on PyPI · released Jul 12, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttp://github.com/deactivated/python-iso3166 ↗

packagehttps://pypi.org/project/iso3166/ ↗