countryinfo

library1.0.1pypypi✓ verified 24d ago

A lightweight Python library for accessing comprehensive country data — including ISO codes, states/provinces, capital cities, currencies, languages, and other geographic information. The current version is 1.0.1. The project maintains an active development status, with the latest release in March 2026.

data

pip install countryinfo

github ↗package ↗

INSTALL

IMPORT

SIG · COUNTRYINFO

countryinfo

datapythonv1.0.1

Install

2.2s avg

Import

33ms

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.2 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.034s · 18.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.2s · import 0.032s · 19MB

32MB installed

● package 32MB

Code

Verified usage

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

CountryInfo

✓ from countryinfo import CountryInfo

CountryNotFoundError

✓ from countryinfo import CountryInfo, CountryNotFoundError

Import CountryNotFoundError for explicit error handling.

Initializes `CountryInfo` with a country name (or ISO code/numeric ID) and demonstrates fetching its capital and ISO code. It also includes error handling for non-existent countries and demonstrates filtering all available countries by region.

from countryinfo import CountryInfo, CountryNotFoundError import os try: # Use a well-known country for the quickstart country = CountryInfo("Singapore") print(f"Capital of Singapore: {country.capital()}") # Example of retrieving ISO information print(f"ISO Alpha-2 code: {country.iso(2)}") # Example with a non-existent country to demonstrate error handling non_existent_country = "Neverland" print(f"\nTrying to get info for '{non_existent_country}':") CountryInfo(non_existent_country).name() except CountryNotFoundError as e: print(f"Error: {e}") except ValueError as e: print(f"Error: {e}") # To demonstrate filtering countries by region print("\nFetching some countries in Europe:") europe_countries = [c['name'] for c in CountryInfo.all().values() if c.get('region') == 'Europe'] if europe_countries: print(f"Example European countries: {', '.join(europe_countries[:5])}...")

Debug

Known issues

gotchaInitializing `CountryInfo` with a non-existent country name will raise a `CountryNotFoundError`.

fix

Wrap the `CountryInfo` constructor in a `try-except CountryNotFoundError` block.

affects: >=1.0.0

gotchaPassing `None` or an empty string to the `CountryInfo` constructor will raise a `ValueError`.

fix

Ensure the input to `CountryInfo` is a non-empty string or a valid integer (for ISO numeric).

affects: >=1.0.0

gotchaRegion names (e.g., 'Africa', 'Europe') are not valid inputs for the `CountryInfo` constructor. It expects specific country identifiers.

fix

To get countries within a region, use `CountryInfo.all()` to retrieve all country data and then filter the results based on the 'region' key.

affects: >=1.0.0

gotchaUsers have reported `KeyError` or issues with data loading, sometimes indicating missing data files or corrupted installations.

fix

Verify the `countryinfo/data` directory exists within your `site-packages` and contains the necessary JSON files. Reinstalling the package might resolve the issue.

affects: >=1.0.0

gotchaEnvironments with non-UTF-8 default encodings may encounter `UnicodeDecodeError` or `charmap` errors when processing certain country names or data.

fix

Ensure your Python environment is configured to use UTF-8 encoding. This can often be set via environment variables (e.g., `PYTHONIOENCODING=UTF-8`) or by running Python with the `-X utf8` flag.

affects: >=1.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'countryinfo'

This error occurs when the `countryinfo` package is not installed in the Python environment or the Python interpreter cannot locate it in its search path.

fix

Install the library using pip: `pip install countryinfo`

country = CountryInfo('NonExistentCountryName') countryinfo.exceptions.CountryNotFoundError: Country not found: 'NonExistentCountryName'

The `CountryInfo` constructor was called with a country name or identifier that does not exist in its internal dataset.

fix

Ensure the country name or ISO code is valid and correctly spelled. Wrap the constructor call in a `try-except CountryNotFoundError` block for robust error handling. Example: `from countryinfo import CountryInfo, CountryNotFoundError
try:
    country = CountryInfo('Singapore')
except CountryNotFoundError as e:
    print(f'Error: {e}')`

ValueError: Input to CountryInfo must be a non-empty string or a valid integer (for ISO numeric).

The `CountryInfo` constructor received `None`, an empty string, or an invalid type as input, or a region name instead of a specific country identifier.

fix

Provide a valid, non-empty string (country name or ISO code) or an integer (ISO numeric code) to the `CountryInfo` constructor. Example: `country = CountryInfo('USA')` or `country = CountryInfo(840)`

KeyError: 'some_country_key'

This error often occurs when trying to access a country's data using an incorrect key, or if the internal data files are missing or corrupted, which prevents the library from finding the requested country or its specific attribute.

fix

Verify the exact keys for accessing country properties (e.g., `country.capital()` instead of `country.capital`). If the error persists after checking keys, reinstall the `countryinfo` package to ensure data files are intact: `pip install --upgrade --force-reinstall countryinfo`.

UnicodeDecodeError: 'charmap' codec can't decode byte 0xa1 in position XX: character maps to <undefined>

This issue typically arises in environments (often Windows) where the default system encoding is not UTF-8, causing problems when the library tries to read its internal JSON data files containing special characters.

fix

Ensure your Python environment is configured to use UTF-8 encoding. You can set the `PYTHONIOENCODING` environment variable to `UTF-8` before running your script, or open the relevant file with `encoding='utf-8'` if manually loading data (though this fix might require modifying the library's source for deeply embedded file operations). Example of setting environment variable (in terminal before running python script): `set PYTHONIOENCODING=UTF-8` (Windows) or `export PYTHONIOENCODING=UTF-8` (Linux/macOS).

Upgrade

Version history

1.0.1latest on PyPI · released Mar 7, 2026

Audit

Dependencies

fuzzyoptionalFor fuzzy/typo-tolerant country lookup (optional)

pydanticoptionalFor Pydantic v2 typed models (optional)

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/porimol/countryinfo ↗

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