MaxMind GeoLite2 Python Wrapper

2018.703 · abandoned · verified Thu Apr 16

maxminddb-geolite2 is a Python library that provides convenient access to MaxMind's GeoLite2 City database. It packages a version of the GeoLite2 City database directly within the Python package, aiming to simplify integration by eliminating the need for separate database downloads for basic usage. The latest release, version 2018.703, was published in July 2018.

Common errors

```
Outdated geolocation data / Inaccurate IP lookups.
```
cause The GeoLite2 database bundled with `maxminddb-geolite2` is from 2018 and does not receive automatic updates. IP address assignments change over time, leading to stale information.

fix To get current geolocation data, download the latest GeoLite2 database (`.mmdb` file) from your MaxMind account (requires registration and a license key). Then, use the lower-level `maxminddb` library to load and query this up-to-date `.mmdb` file.
```
maxminddb.errors.InvalidDatabaseError: The MaxMind DB file's data section contains bad data: invalid size of double.
```
cause This error typically indicates that the underlying GeoLite2 database file is corrupted or incomplete. It might occur if a download was interrupted, or the file was incorrectly handled.

fix Reinstall `maxminddb-geolite2` to ensure a fresh, uncorrupted bundled database, or if using a manually supplied database, redownload the `.mmdb` file from MaxMind's website to ensure its integrity.
```
Cannot connect to MaxMind for updates / MaxMind GeoLite2 update failed / 401 Unauthorized during database download.
```
cause The `maxminddb-geolite2` library does not include functionality to update the GeoLite2 database. MaxMind discontinued public downloads in 2019, requiring account credentials and a license key for all GeoLite2 database access, which this library does not support.

fix This library is not designed for database updates. To keep GeoLite2 data current, register for a MaxMind account, obtain a license key, and use MaxMind's `geoipupdate` program or a custom script to download the latest `.mmdb` files, then use the `maxminddb` library to access them.

Warnings

breaking MaxMind deprecated public GeoLite2 database downloads in December 2019, requiring users to register for an account and obtain a license key. This library, last updated in July 2018, does not support this new authentication mechanism, making it impossible to update the bundled database via the library itself.
Fix: This library cannot be used to automatically fetch current GeoLite2 databases. To use up-to-date data, users must manually obtain a GeoLite2 database (`.mmdb` file) from MaxMind (requiring a MaxMind account and license key) and use the `maxminddb` library directly, or use MaxMind's `geoipupdate` tool.
gotcha The GeoLite2 database bundled with this library (version 2018.703) is significantly outdated. IP address allocations and geographic data change frequently, leading to potentially inaccurate or incorrect geolocation results for many IP addresses.
Fix: Always use the most current GeoLite2 database available from MaxMind for accurate results. This requires manual download and integration with the `maxminddb` library, as this wrapper cannot update its bundled data.
gotcha The `maxminddb-geolite2` library appears to be unmaintained, with its last release in 2018. This means it may not be compatible with newer Python versions, have unpatched bugs, or not support modern MaxMind DB features.
Fix: Consider migrating to the official `maxminddb` library and managing GeoLite2 database downloads and updates independently using MaxMind's recommended tools (e.g., `geoipupdate`).

Install

pip install maxminddb-geolite2 Install from PyPI

Imports

geolite2
```
from geolite2 import geolite2
```

Quickstart

Initialise the geolite2 reader and perform an IP lookup. Remember to close the reader when done to free up resources.

from geolite2 import geolite2

reader = geolite2.reader()
ip_address = '8.8.8.8' # Google Public DNS

# Lookup IP address
geodata = reader.get(ip_address)

if geodata:
    print(f"Geolocation for {ip_address}:")
    print(f"  Country: {geodata.get('country', {}).get('names', {}).get('en')}")
    print(f"  City: {geodata.get('city', {}).get('names', {}).get('en')}")
    print(f"  Latitude: {geodata.get('location', {}).get('latitude')}")
    print(f"  Longitude: {geodata.get('location', {}).get('longitude')}")
else:
    print(f"No geolocation data found for {ip_address}")

# It's important to close the reader to release resources
geolite2.close()

view raw JSON →