ip3country

0.4.0 · active · verified Thu Apr 09

ip3country is a Python library providing a zero-dependency, local, fast, and tiny solution for looking up the two-letter country code associated with an IPv4 address. It bundles its own IP-to-country database, eliminating external dependencies or network calls for lookups. The current version is 0.4.0, and it maintains a moderate release cadence, focusing on stability and minimal overhead.

Warnings

gotcha The 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.
Fix: Regularly update the library using `pip install --upgrade ip3country` to ensure the data is current.
gotcha The `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`.
Fix: Ensure all input IP addresses are valid IPv4 strings. For IPv6 lookups, consider an alternative library.
gotcha The `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.
Fix: Initialize a single `Ip3Country` instance once (e.g., at application startup) and reuse that instance for all IP lookups throughout the application's lifecycle.

Install

pip install ip3country Install ip3country

Imports

Ip3Country
```
from ip3country import Ip3Country
```

Quickstart

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

view raw JSON →