{"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":"en","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":[{"symbol":"Ip3Country","correct":"from ip3country import Ip3Country"}],"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"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}