maxminddb

library3.1.1pypypi✓ verified 25d ago

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.

data http-networking

pip install maxminddb

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · MAXMINDDB

maxminddb

datapythonv3.1.1

Install

1.6s avg

Import

138ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.144s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.132s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

open_database

✓ from maxminddb import open_database

Mode

✓ from maxminddb import Mode

InvalidDatabaseError

✓ from maxminddb import InvalidDatabaseError

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

Debug

Known issues

gotchaCalling 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.

affects: All versions

gotchaAttempting 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`).

affects: All versions

gotchaWhen 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`.

affects: All versions

gotchaThe `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()`.

affects: All versions

Errors

Common errors & fixes

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

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.

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

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.

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

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.

ModuleNotFoundError: No module named 'maxminddb'

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.

Upgrade

Version history

3.1.1latest on PyPI · released Mar 5, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/maxmind/MaxMind-DB-Reader-python ↗

packagehttps://pypi.org/project/maxminddb/ ↗

homepagehttps://www.maxmind.com/ ↗

docshttps://maxminddb.readthedocs.org/ ↗