Repository files navigation

This is a Python module for reading MaxMind DB files. The module includes botha pure Python reader and an optional C extension.

MaxMind DB is a binary file format that stores data indexed by IP addresssubnets (IPv4 or IPv6).

To installmaxminddb, type:

$ pip install maxminddb

If you are not able to install from PyPI, you may also usepip from thesource directory:

$ python -m pip install.

The installer will attempt to build the C extension. If this fails, themodule will fall-back to the pure Python implementation.

To use this module, you must first download or create a MaxMind DB file. Weprovidefree GeoLite2 databases. Thesefiles must be decompressed withgunzip.

After you have obtained a database and imported the module, callopen_database with a path, or file descriptor (in the case ofMODE_FD),to the database as the first argument. Optionally, you may pass a mode as thesecond argument. The modes are exported frommaxminddb. Valid modes are:

• MODE_MMAP_EXT - use the C extension with memory map.
• MODE_MMAP - read from memory map. Pure Python.
• MODE_FILE - read database as standard file. Pure Python.
• MODE_MEMORY - load database into memory. Pure Python.
• MODE_FD - load database into memory from a file descriptor. Pure Python.
• MODE_AUTO - tryMODE_MMAP_EXT,MODE_MMAP,MODE_FILE in thatorder. Default.

NOTE: When usingMODE_FD, it is thecaller's responsibility to besure that the file descriptor gets closed properly. The caller may close thefile descriptor immediately after theReader object is created.

Theopen_database function returns aReader object. To look up an IPaddress, use theget method on this object. The method will return thecorresponding values for the IP address from the database (e.g., a dictionaryfor GeoIP2/GeoLite2 databases). If the database does not contain a record forthat IP address, the method will returnNone.

If you wish to also retrieve the prefix length for the record, use theget_with_prefix_len method. This returns a tuple containing the recordfollowed by the network prefix length associated with the record.

You may also iterate over the whole database. TheReader class implementsthe__iter__ method that returns an iterator. This iterator yields atuple containing the network and the record.

>>>import maxminddb>>>>>>with maxminddb.open_database('GeoLite2-City.mmdb')as reader:>>>>>>     reader.get('152.216.7.110'){'country': ... }>>>>>>     reader.get_with_prefix_len('152.216.7.110')({'country': ... }, 24)>>>>>>for network, recordin reader:>>>...

The module will return anInvalidDatabaseError if the database is corruptor otherwise invalid. AValueError will be thrown if you look up aninvalid IP address or an IPv6 address in an IPv4 database.

Both the C extension and pure Python implementations are safe for concurrentreads and support Python 3.13+ free-threading. The C extension providesfree-threading support on platforms with pthread support (such as Linux andmacOS) and Windows. On other platforms, the extension will use GIL-basedprotection. Callingclose() while reads are in progress may causeexceptions in those threads.

This code requires Python 3.10+. Older versions are not supported. The Cextension requires CPython.

The MaxMind DB Python module usesSemantic Versioning.

Please report all issues with this code using theGitHub issue tracker

If you are having an issue with a MaxMind service that is not specific to thisAPI, please contactMaxMind support forassistance.