# MaxMind DB Python Module

## Description

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

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

## Installation

To install `maxminddb`, type:

    $ pip install maxminddb

If you are not able to install from PyPI, you may also use `pip` from the source directory:

    $ python -m pip install .

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

## Usage

To use this module, you must first download or create a MaxMind DB file. We provide free GeoLite2 databases. These files must be decompressed with `gunzip`.

After you have obtained a database and imported the module, call `open_database` with a path, or file descriptor (in the case of `Mode.FD`), to the database as the first argument. Optionally, you may pass a mode as the second argument. The modes are available from `maxminddb.Mode`. 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` - try `Mode.MMAP_EXT`, `Mode.MMAP`, `Mode.FILE` in that order. Default.

NOTE: When using `Mode.FD`, it is the caller’s responsibility to be sure that the file descriptor gets closed properly. The caller may close the file descriptor immediately after the `Reader` object is created.

The `open_database` function returns a `Reader` object. To look up an IP address, use the `get` method on this object. The method will return the corresponding values for the IP address from the database (e.g., a dictionary for GeoIP2/GeoLite2 databases). If the database does not contain a record for that IP address, the method will return `None`.

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

You may also iterate over the whole database. The `Reader` class implements the `__iter__` method that returns an iterator. This iterator yields a tuple containing the network and the record.

## Example

    >>> 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, record in reader:
    >>>         ...

## Exceptions

The module will return an `InvalidDatabaseError` if the database is corrupt or otherwise invalid. A `ValueError` will be thrown if you look up an invalid IP address or an IPv6 address in an IPv4 database.

## Thread Safety

Both the C extension and pure Python implementations are safe for concurrent reads and support Python 3.13+ free-threading. The C extension provides free-threading support on platforms with pthread support (such as Linux and macOS) and Windows. On other platforms, the extension will use GIL-based protection. Calling `close()` while reads are in progress may cause exceptions in those threads.

## Requirements

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

## Versioning

The MaxMind DB Python module uses Semantic Versioning.

## Support

Please report all issues with this code using the GitHub issue tracker

If you are having an issue with a MaxMind service that is not specific to this API, please contact MaxMind support for assistance.

# Module

Module for reading MaxMind DB files.

exception maxminddb.InvalidDatabaseError

  Bases: `RuntimeError`

  An error thrown when unexpected data is found in the database.

class maxminddb.Reader(database: AnyStr | int | PathLike | IO, mode: int = Mode.AUTO)

  Bases: `object`

  A pure Python implementation of a reader for the MaxMind DB format.

  IP addresses can be looked up using the `get` method.

  close() → None

    Close the MaxMind DB file and returns the resources to the system.

    Calling this method while reads are in progress may cause exceptions.

  closed: bool
  get(ip_address: str | IPv6Address | IPv4Address) → Record | None

    Return the record for the ip_address in the MaxMind DB.

    Arguments:

      ip_address: an IP address in the standard string notation

  get_with_prefix_len(ip_address: str | IPv6Address | IPv4Address) → tuple[Record | None, int]

    Return a tuple with the record and the associated prefix length.

    Arguments:

      ip_address: an IP address in the standard string notation

  metadata() → Metadata

    Return the metadata associated with the MaxMind DB file.

maxminddb.open_database(database: AnyStr | int | os.PathLike | IO, mode: int = Mode.AUTO) → Reader

  Open a MaxMind DB database.

  Arguments:
    database: A path to a valid MaxMind DB file such as a GeoIP2 database

      file, or a file descriptor in the case of MODE_FD.

    mode: mode to open the database with. Valid mode 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 - the param passed via database is a file descriptor, not

          a path. This mode implies MODE_MEMORY.

      - MODE_AUTO - tries MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that

          order. Default mode.

# Errors

Typed errors thrown by this library.

exception maxminddb.errors.InvalidDatabaseError

  Bases: `RuntimeError`

  An error thrown when unexpected data is found in the database.

# Database Reader

Pure-Python reader for the MaxMind DB file format.

class maxminddb.reader.Metadata(*, binary_format_major_version: int, binary_format_minor_version: int, build_epoch: int, database_type: str, description: dict[str, str], ip_version: int, languages: list[str], node_count: int, record_size: int)

  Bases: `object`

  Metadata for the MaxMind DB reader.

  binary_format_major_version: int

    The major version number of the binary format used when creating the database.

  binary_format_minor_version: int

    The minor version number of the binary format used when creating the database.

  build_epoch: int

    The Unix epoch for the build time of the database.

  database_type: str

    A string identifying the database type, e.g., “GeoIP2-City”.

  description: dict[str, str]

    A map from locales to text descriptions of the database.

  ip_version: int

    The IP version of the data in a database. A value of “4” means the database only supports IPv4. A database with a value of “6” may support both IPv4 and IPv6 lookups.

  languages: list[str]

    A list of locale codes supported by the database.

  property node_byte_size: int

    The size of a node in bytes.

  node_count: int

    The number of nodes in the database.

  record_size: int

    The bit size of a record in the search tree.

  property search_tree_size: int

    The size of the search tree.

class maxminddb.reader.Reader(database: AnyStr | int | PathLike | IO, mode: int = Mode.AUTO)

  Bases: `object`

  A pure Python implementation of a reader for the MaxMind DB format.

  IP addresses can be looked up using the `get` method.

  close() → None

    Close the MaxMind DB file and returns the resources to the system.

    Calling this method while reads are in progress may cause exceptions.

  closed: bool
  get(ip_address: str | IPv6Address | IPv4Address) → Record | None

    Return the record for the ip_address in the MaxMind DB.

    Arguments:

      ip_address: an IP address in the standard string notation

  get_with_prefix_len(ip_address: str | IPv6Address | IPv4Address) → tuple[Record | None, int]

    Return a tuple with the record and the associated prefix length.

    Arguments:

      ip_address: an IP address in the standard string notation

  metadata() → Metadata

    Return the metadata associated with the MaxMind DB file.

# Indices and tables

- Index

- Module Index

- Search Page

copyright:

  3. 2013-2025 by MaxMind, Inc.

license:

  Apache License, Version 2.0