{"id":997,"library":"maxminddb","title":"MaxMind DB Python Reader","description":"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.","status":"active","version":"3.1.1","language":"python","source_language":"en","source_url":"https://github.com/maxmind/MaxMind-DB-Reader-python","tags":["database","geoip","ip-lookup","maxmind"],"install":[{"cmd":"pip install maxminddb","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"open_database","correct":"from maxminddb import open_database"},{"symbol":"Mode","correct":"from maxminddb import Mode"},{"symbol":"InvalidDatabaseError","correct":"from maxminddb import InvalidDatabaseError"}],"quickstart":{"code":"import maxminddb\nimport os\n\n# You need a MaxMind DB file, e.g., GeoLite2-City.mmdb.\n# Download free GeoLite2 databases from maxmind.com.\ndatabase_path = os.environ.get('MAXMIND_DB_PATH', 'GeoLite2-City.mmdb')\n\ntry:\n    with maxminddb.open_database(database_path) as reader:\n        # Look up an IPv4 address\n        ip_address_v4 = '152.216.7.110'\n        record_v4 = reader.get(ip_address_v4)\n        print(f'Record for {ip_address_v4}: {record_v4}')\n\n        # Look up an IPv6 address (if database supports it)\n        ip_address_v6 = '2001:4860:4860::8888'\n        record_v6 = reader.get(ip_address_v6)\n        print(f'Record for {ip_address_v6}: {record_v6}')\n\n        # Get metadata about the database\n        metadata = reader.metadata()\n        print(f'Database Type: {metadata.database_type}')\n\n        # Iterate over all networks and records (can be slow for large DBs)\n        # for network, record in reader:\n        #     print(f'Network: {network}, Record: {record}')\n\nexcept maxminddb.InvalidDatabaseError as e:\n    print(f'Error opening or reading database: {e}')\nexcept ValueError as e:\n    print(f'Invalid IP address or incompatible database for IP version: {e}')\nexcept FileNotFoundError:\n    print(f'Database file not found at: {database_path}')","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure all read operations are complete or synchronized before calling `reader.close()` or exiting a `with maxminddb.open_database(...)` block.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Validate IP addresses before lookup and ensure the database supports the IP version being queried (e.g., check `reader.metadata().ip_version`).","message":"Attempting to look up an invalid IP address string or an IPv6 address in an IPv4-only database will raise a `ValueError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually close the file descriptor after passing it to `open_database` when using `Mode.FD`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Obtain a valid MaxMind DB file and provide its path to `maxminddb.open_database()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:27:56.758Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'GeoLite2-City.mmdb'"},{"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.","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.","error":"maxminddb.errors.InvalidDatabaseError: The MaxMind DB file's search tree is corrupt"},{"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.","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.","error":"ValueError: '::1' is not a valid IPv4 address"},{"fix":"Install the package using pip: `pip install maxminddb`. If using a virtual environment, ensure it is activated before installation and execution.","cause":"The `maxminddb` Python package has not been installed in the current Python environment, or the environment where it was installed is not active.","error":"ModuleNotFoundError: No module named 'maxminddb'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.1","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.9,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.11,"mem_mb":5,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":5,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":5.7,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":5.7,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.17,"mem_mb":5.9,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":5.9,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.7,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":5.7,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.19,"mem_mb":5.7,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.7,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":5.5,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.5,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.16,"mem_mb":5.5,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":5.5,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.6,"disk_size":"17.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.6,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.04,"mem_mb":1.6,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.6,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}