Install & Compatibility
Where this runs
tested against v0.4.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.006s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CountryLookup
✓ from ip3country import CountryLookup
✗ from ip3country import Ip3Country
country_lookup
✓ from ip3country import country_lookup
✗ from ip3country import Ip3Country
Initialize the `Ip3Country` class once to load its local IP-to-country database into memory. Then, use the `lookup_ip` method to retrieve the two-letter country code for a given IPv4 address string.
from ip3country import Ip3Country
# Initialize the lookup instance once. This loads the data in memory.
lookup = Ip3Country()
# Lookup an IPv4 address
ip_address_us = "8.8.8.8"
country_code_us = lookup.lookup_ip(ip_address_us)
print(f"IP {ip_address_us} is in {country_code_us}") # Expected: US
ip_address_local = "127.0.0.1"
country_code_local = lookup.lookup_ip(ip_address_local)
print(f"IP {ip_address_local} is in {country_code_local}") # Expected: None or unknown
Debug
Known issues
gotchaThe IP-to-country data is bundled directly with the library and is not automatically updated. To get the latest IP mappings, users must explicitly upgrade the `ip3country` library to a newer version when available.fixRegularly update the library using `pip install --upgrade ip3country` to ensure the data is current.
affects: All versions
gotchaThe `ip3country` library currently only supports IPv4 addresses. Attempting to pass an IPv6 address string to the `lookup_ip` method will likely result in an error (e.g., `socket.error` or `OSError`) or return `None`.fixEnsure all input IP addresses are valid IPv4 strings. For IPv6 lookups, consider an alternative library.
affects: All versions
gotchaThe `Ip3Country()` constructor loads the entire IP database into memory. While fast for subsequent lookups, repeatedly calling the constructor (e.g., inside a loop or for every request) is inefficient and can lead to performance issues or increased memory usage.fixInitialize a single `Ip3Country` instance once (e.g., at application startup) and reuse that instance for all IP lookups throughout the application's lifecycle.
affects: All versions
breakingThe main class `Ip3Country` cannot be imported from the `ip3country` package. This indicates a potential change in the library's API (e.g., class name or module path) or an issue with the library's installation/packaging that prevents its core functionality from being accessed.fixVerify the correct class name and import path according to the library's documentation. If the library has been updated, consult its changelog for API breaking changes. Ensure the `ip3country` package is correctly installed.
affects: All versions
breakingThe main `Ip3Country` class cannot be imported from the `ip3country` package. This indicates a critical issue preventing library usage, potentially due to an incompatibility with the Python version (e.g., Python 3.13), a breaking API change in the installed library version, or an installation problem specific to the environment.fixCheck the official documentation or release notes for `ip3country` to confirm the correct import statement and API for the installed version, especially regarding Python 3.13 compatibility. Consider installing a specific, older version of the library known to be stable with your Python interpreter, or use a different Python version.
affects: All versions on Python 3.13-alpine (and potentially later Python versions or other specific environments).
Upgrade
Version history
0.4.0latest on PyPI · released Jul 10, 2025
Audit
Dependencies
No dependency data recorded yet.