Install & Compatibility
Where this runs
tested against v1.2.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.106s · 30.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.110s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GeoIP2Fast
✓ from geoip2fast import GeoIP2Fast
Initializes the GeoIP2Fast library with a specified data file and performs IP lookups for both IPv4 and IPv6 addresses. It demonstrates how to retrieve country name and ASN details, and handles private IP addresses. It includes error handling for missing data files.
import os
from geoip2fast import GeoIP2Fast
# Ensure data file is present, or download it. For this example, we assume it's in the current directory.
# In a real application, you might use GeoIP2Fast.update_all() or provide a path to an existing file.
# For demonstration, we'll try to use a common data file that might be downloaded separately.
# If not found, a FileNotFoundError will be raised, indicating the data file needs to be obtained.
data_file = os.environ.get('GEOIP2FAST_DATA_FILE', 'geoip2fast-asn-ipv6.dat.gz')
try:
# Initialize GeoIP2Fast with a specific data file (e.g., with ASN and IPv6 support)
# The library looks in the current directory and then in the library's package directory.
geoip = GeoIP2Fast(geoip2fast_data_file=data_file, verbose=False)
# Lookup an IPv4 address
ip_v4 = "8.8.8.8"
result_v4 = geoip.lookup(ip_v4)
print(f"IPv4 Lookup for {ip_v4}: {result_v4.country_name}, ASN: {result_v4.asn_name}")
# Lookup an IPv6 address
ip_v6 = "2001:4860:4860::8888"
result_v6 = geoip.lookup(ip_v6)
print(f"IPv6 Lookup for {ip_v6}: {result_v6.country_name}, ASN: {result_v6.asn_name}")
# Example of a private IP address
private_ip = "192.168.1.1"
result_private = geoip.lookup(private_ip)
print(f"Private IP {private_ip}: is_private={result_private.is_private}")
except FileNotFoundError:
print(f"Error: GeoIP2Fast data file '{data_file}' not found.")
print("Please download the necessary .dat.gz file from the GitHub releases (e.g., https://github.com/rabuchaim/geoip2fast/releases/tag/LATEST) and place it in the application directory or specify its path.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingData files for GeoIP2Fast v1.2.x are not compatible with v1.1.x (and older versions), and vice-versa. Ensure you use the correct data file version corresponding to your installed library version.fixDownload the appropriate '.dat.gz' file from the GitHub releases page for your installed library version. For v1.2.x, look for the 'LATEST' tag; for v1.1.x, look for the 'LEGACY' tag.
affects: >=1.2.0 (incompatible with <1.2.0)
gotchaGeoIP2Fast requires a data file (`.dat.gz`) for lookups. While the library can download data files using `GeoIP2Fast.update_all()`, you might need to manually download a specific variant (e.g., for City or ASN data) and place it in your application's directory or specify its path.fixInitialize `GeoIP2Fast` with the `geoip2fast_data_file` argument pointing to your desired `.dat.gz` file, or ensure the default `geoip2fast.dat.gz` is present in your application or library path. Data files are available on the GitHub releases page.
affects: All versions
gotchaWhen an IP address is not found in the database, GeoIP2Fast explicitly returns 'not found in database' rather than falling back to a less precise geographical location. This is by design to ensure accuracy.fixHandle the 'not found in database' result in your application logic if a lookup does not yield a specific entry. The result object will still be returned, but fields like `country_name` might be empty or indicate 'not found'.
affects: All versions
deprecatedThe line `sys.tracebacklimit = 0` was removed in v1.2.2 as it caused issues in environments like Django. If you relied on this behavior, be aware it's no longer present.fixRemove any custom overrides or expectations based on `sys.tracebacklimit = 0` when upgrading to v1.2.2 or newer.
affects: >=1.2.2
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'geoip2fast.dat.gz'
The required GeoIP2Fast data file (or the specified custom file) could not be found by the library.
fixEnsure the `geoip2fast.dat.gz` (or your chosen data file, e.g., `geoip2fast-asn-ipv6.dat.gz`) is present in the same directory as your script or in the `site-packages/geoip2fast` directory. Alternatively, specify the full path to the data file when initializing `GeoIP2Fast(geoip2fast_data_file='/path/to/your/file.dat.gz')`. Download the latest files from the official GitHub releases.
network not found in database
The IP address queried exists, but its network block is not present in the loaded GeoIP2Fast database.
fixThis is an intended behavior of GeoIP2Fast; it does not infer location for IPs not explicitly in its database. Verify the IP is valid and consider if a different, more comprehensive (and possibly larger) data file (e.g., a city/ASN database) might contain the entry if available.
invalid ip address
The input string provided for lookup is not a syntactically valid IPv4 or IPv6 address.
fixCheck the format of the IP address string being passed to the `lookup()` method. Ensure it adheres to standard IPv4 (e.g., '192.168.1.1') or IPv6 (e.g., '2001:0db8::') notation.
Upgrade
Version history
1.2.2latest on PyPI · released Jun 21, 2024
Audit
Dependencies
No dependency data recorded yet.