{"id":1515,"library":"ip3country","title":"ip3country","description":"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.","status":"active","version":"0.4.0","language":"python","source_language":"en","source_url":"https://github.com/statsig-io/ip3country-py","tags":["ip-address","geolocation","country-lookup","zero-dependency","offline","ipv4"],"install":[{"cmd":"pip install ip3country","lang":"bash","label":"Install ip3country"}],"dependencies":[],"imports":[{"wrong":"from ip3country import Ip3Country","symbol":"CountryLookup","correct":"from ip3country import CountryLookup"},{"wrong":"from ip3country import Ip3Country","symbol":"country_lookup","correct":"from ip3country import country_lookup"}],"quickstart":{"code":"from ip3country import Ip3Country\n\n# Initialize the lookup instance once. This loads the data in memory.\nlookup = Ip3Country()\n\n# Lookup an IPv4 address\nip_address_us = \"8.8.8.8\"\ncountry_code_us = lookup.lookup_ip(ip_address_us)\nprint(f\"IP {ip_address_us} is in {country_code_us}\") # Expected: US\n\nip_address_local = \"127.0.0.1\"\ncountry_code_local = lookup.lookup_ip(ip_address_local)\nprint(f\"IP {ip_address_local} is in {country_code_local}\") # Expected: None or unknown","lang":"python","description":"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."},"warnings":[{"fix":"Regularly update the library using `pip install --upgrade ip3country` to ensure the data is current.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all input IP addresses are valid IPv4 strings. For IPv6 lookups, consider an alternative library.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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.","message":"The 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Check 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.","message":"The 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.","severity":"breaking","affected_versions":"All versions on Python 3.13-alpine (and potentially later Python versions or other specific environments)."}],"env_vars":null,"search_vec":"'0.4.0':52 'address':30,68 'associ':26 'bundl':32 'cadenc':59 'call':45 'code':25 'countri':24,38,71 'country-lookup':70 'current':49 'databas':39 'depend':11,42,75 'elimin':40 'extern':41 'fast':13 'focus':60 'geoloc':69 'ip':36,67 'ip-address':66 'ip-to-countri':35 'ip3country':1,2 'ipv4':29,77 'letter':23 'librari':6 'local':12 'look':18 'lookup':47,72 'maintain':55 'minim':64 'moder':57 'network':44 'offlin':76 'overhead':65 'provid':7 'python':5 'releas':58 'solut':16 'stabil':62 'tini':15 'two':22 'two-lett':21 'version':50 'zero':10,74 'zero-depend':9,73","created_at":"2026-04-09T03:51:15.146683+00:00","updated_at":"2026-04-16T15:46:58.479814+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/statsig-io/ip3country-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ip3country/","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-30","last_verified":"2026-08-27","next_check":"2026-07-30","install_tag":"stale"}}