GeoIP2Fast

1.2.2 · active · verified Thu Apr 16

GeoIP2Fast is a high-performance Python library for GeoIP2 country, city, and ASN lookups, supporting both IPv4 and IPv6. It boasts lookup speeds of less than 0.00003 seconds and utilizes its own data files, updated twice a week with MaxMind GeoLite2 CSV data. The library is pure Python, has no external dependencies, and is currently at version 1.2.2.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'geoip2fast.dat.gz'
```
cause The required GeoIP2Fast data file (or the specified custom file) could not be found by the library.

fix Ensure 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
```
cause The IP address queried exists, but its network block is not present in the loaded GeoIP2Fast database.

fix This 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
```
cause The input string provided for lookup is not a syntactically valid IPv4 or IPv6 address.

fix Check 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.

Warnings

breaking Data 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.
Fix: Download 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.
gotcha GeoIP2Fast 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.
Fix: Initialize `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.
gotcha When 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.
Fix: Handle 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'.
deprecated The 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.
Fix: Remove any custom overrides or expectations based on `sys.tracebacklimit = 0` when upgrading to v1.2.2 or newer.

Install

pip install geoip2fast Install stable version

Imports

GeoIP2Fast
```
from geoip2fast import GeoIP2Fast
```

Quickstart

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}")

view raw JSON →