MaxMind DB Python Reader

3.1.1 verified Tue May 12 auth: no python install: verified

This is a Python module for reading MaxMind DB files, a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6). The library includes both a pure Python reader and an optional C extension for performance. It is actively maintained, with version 3.1.1 released on March 5, 2026, and follows Semantic Versioning.

pip install maxminddb

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: 'GeoLite2-City.mmdb' ↓

cause The specified MaxMind DB file (e.g., GeoLite2-City.mmdb) does not exist at the given path, either because it hasn't been downloaded or the path is incorrect.

fix

Download the GeoLite2 database file from MaxMind's website (requires a free account) and ensure the path provided to maxminddb.open_database() is correct. The files often need to be decompressed with gunzip after download.

error maxminddb.errors.InvalidDatabaseError: The MaxMind DB file's search tree is corrupt ↓

cause The MaxMind DB file is corrupted, malformed, or not in a format supported by the reader, which can happen if the download was incomplete or the file was generated incorrectly.

fix

Re-download the MaxMind DB file to ensure it is complete and uncorrupted. Verify that the database file is compatible with the maxminddb library version being used.

error ValueError: '::1' is not a valid IPv4 address ↓

cause An attempt was made to look up an invalid IP address string, or an IPv6 address was provided to a database that only supports IPv4 lookups.

fix

Ensure the IP address string is valid and that you are not attempting to look up an IPv6 address in an IPv4-only database. For instance, if you have an IPv4-only database, convert IPv6 addresses to their IPv4-mapped equivalent if applicable, or use an IPv6-compatible database.

error ModuleNotFoundError: No module named 'maxminddb' ↓

cause The `maxminddb` Python package has not been installed in the current Python environment, or the environment where it was installed is not active.

fix

Install the package using pip: pip install maxminddb. If using a virtual environment, ensure it is activated before installation and execution.

Warnings

gotcha Calling the `close()` method on a `Reader` object while reads are in progress in other threads may cause exceptions. The library is thread-safe for concurrent reads but closing should be done when no reads are active. ↓

fix Ensure all read operations are complete or synchronized before calling `reader.close()` or exiting a `with maxminddb.open_database(...)` block.

gotcha Attempting to look up an invalid IP address string or an IPv6 address in an IPv4-only database will raise a `ValueError`. ↓

fix Validate IP addresses before lookup and ensure the database supports the IP version being queried (e.g., check `reader.metadata().ip_version`).

gotcha When opening a database with `maxminddb.Mode.FD` (file descriptor mode), it is the caller's responsibility to ensure the file descriptor is closed properly. The library will not manage the file descriptor's lifecycle. ↓

fix Manually close the file descriptor after passing it to `open_database` when using `Mode.FD`.

gotcha The `maxminddb` library only reads MaxMind DB files. You must first download or create a `.mmdb` database file (e.g., GeoLite2 from MaxMind) to use the library effectively. ↓

fix Obtain a valid MaxMind DB file and provide its path to `maxminddb.open_database()`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.15s 18.0M

3.10 alpine (musl) - - 0.18s 18.0M

3.10 slim (glibc) wheel 1.5s 0.11s 19M

3.10 slim (glibc) - - 0.10s 19M

3.11 alpine (musl) wheel - 0.19s 19.9M

3.11 alpine (musl) - - 0.22s 19.9M

3.11 slim (glibc) wheel 1.6s 0.17s 20M

3.11 slim (glibc) - - 0.16s 20M

3.12 alpine (musl) wheel - 0.17s 11.8M

3.12 alpine (musl) - - 0.19s 11.8M

3.12 slim (glibc) wheel 1.5s 0.19s 12M

3.12 slim (glibc) - - 0.17s 12M

3.13 alpine (musl) wheel - 0.16s 11.5M

3.13 alpine (musl) - - 0.17s 11.4M

3.13 slim (glibc) wheel 1.5s 0.16s 12M

3.13 slim (glibc) - - 0.18s 12M

3.9 alpine (musl) wheel - 0.06s 17.5M

3.9 alpine (musl) - - 0.05s 17.5M

3.9 slim (glibc) wheel 1.8s 0.04s 18M

3.9 slim (glibc) - - 0.04s 18M

Imports

open_database
```
from maxminddb import open_database
```
Mode
```
from maxminddb import Mode
```

InvalidDatabaseError

from maxminddb import InvalidDatabaseError

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to open a MaxMind DB file using a context manager, perform IP lookups with `get()`, and retrieve database metadata. A valid MaxMind DB file (like a GeoLite2-City.mmdb) is required. Ensure the database file exists at the specified path or in the environment variable `MAXMIND_DB_PATH`.

import maxminddb
import os

# You need a MaxMind DB file, e.g., GeoLite2-City.mmdb.
# Download free GeoLite2 databases from maxmind.com.
database_path = os.environ.get('MAXMIND_DB_PATH', 'GeoLite2-City.mmdb')

try:
    with maxminddb.open_database(database_path) as reader:
        # Look up an IPv4 address
        ip_address_v4 = '152.216.7.110'
        record_v4 = reader.get(ip_address_v4)
        print(f'Record for {ip_address_v4}: {record_v4}')

        # Look up an IPv6 address (if database supports it)
        ip_address_v6 = '2001:4860:4860::8888'
        record_v6 = reader.get(ip_address_v6)
        print(f'Record for {ip_address_v6}: {record_v6}')

        # Get metadata about the database
        metadata = reader.metadata()
        print(f'Database Type: {metadata.database_type}')

        # Iterate over all networks and records (can be slow for large DBs)
        # for network, record in reader:
        #     print(f'Network: {network}, Record: {record}')

except maxminddb.InvalidDatabaseError as e:
    print(f'Error opening or reading database: {e}')
except ValueError as e:
    print(f'Invalid IP address or incompatible database for IP version: {e}')
except FileNotFoundError:
    print(f'Database file not found at: {database_path}')