{"id":4828,"library":"types-maxminddb","title":"Typing Stubs for maxminddb","description":"This package provides type hints for the `maxminddb` Python library, which is used for reading MaxMind DB files. These files store data indexed by IP address subnets (IPv4 or IPv6). `types-maxminddb` ensures that static type checkers like MyPy can validate usage of `maxminddb`. It is part of the `typeshed` project and its release cadence is tied to `typeshed` updates and `maxminddb`'s own releases. The current version is 1.5.0.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","maxminddb","geoip","geolocation","typeshed"],"install":[{"cmd":"pip install types-maxminddb","lang":"bash","label":"Install only type stubs"},{"cmd":"pip install maxminddb types-maxminddb","lang":"bash","label":"Install runtime library and type stubs"}],"dependencies":[{"reason":"Provides the runtime library for which these are type stubs. `types-maxminddb` offers no runtime functionality on its own.","package":"maxminddb","optional":false}],"imports":[{"symbol":"Reader","correct":"from maxminddb import Reader"},{"symbol":"open_database","correct":"from maxminddb import open_database"},{"note":"Other modes like `MODE_FILE`, `MODE_MEMORY`, `MODE_AUTO`, `MODE_FD`, `MODE_MMAP_EXT` are also available from `maxminddb`.","symbol":"MODE_MMAP","correct":"from maxminddb import MODE_MMAP"},{"symbol":"InvalidDatabaseError","correct":"from maxminddb import InvalidDatabaseError"}],"quickstart":{"code":"import maxminddb\nimport os\nfrom typing import Optional, Dict, Any\n\n# You need a MaxMind DB file, e.g., GeoLite2-City.mmdb.\n# Download a free GeoLite2 database from MaxMind: https://dev.maxmind.com/geoip/downloads/\n# For local testing, place it in the current directory or set the environment variable.\nDB_PATH = os.environ.get('MAXMIND_DB_PATH', 'GeoLite2-City.mmdb')\n\nif not os.path.exists(DB_PATH):\n    print(f\"Warning: MaxMind DB file not found at {DB_PATH}.\\n\"\n          \"Please download one (e.g., GeoLite2-City.mmdb) and set MAXMIND_DB_PATH environment variable or place it in the current directory.\")\n    # Create a dummy file for the quickstart to be runnable, but advise user\n    # that it won't actually work without a real DB.\n    with open(DB_PATH, 'w') as f:\n        f.write('dummy_db_content')\n    dummy_db_used = True\nelse:\n    dummy_db_used = False\n\ntry:\n    # `reader` is inferred to be of type `maxminddb.Reader` due to type stubs\n    with maxminddb.open_database(DB_PATH) as reader:\n        ip_address = '8.8.8.8'\n        record: Optional[Dict[str, Any]] = reader.get(ip_address)\n\n        if record:\n            print(f\"Lookup for {ip_address}: {record}\")\n            # Example of accessing typed data if schema is known, e.g., GeoLite2-City\n            country_name: Optional[str] = record.get('country', {}).get('names', {}).get('en')\n            print(f\"  Country (EN): {country_name}\")\n        else:\n            print(f\"No record found for {ip_address}\")\n\n        # Iterate over the database (useful for inspection)\n        print(\"\\nFirst 3 networks and records:\")\n        count = 0\n        for network, record in reader: # `network` is IPv4Network or IPv6Network, `record` is Dict\n            if count >= 3:\n                break\n            print(f\"  Network: {network}, Record: {record}\")\n            count += 1\n\nexcept maxminddb.InvalidDatabaseError as e:\n    print(f\"Error opening MaxMind DB: {e}. Ensure {DB_PATH} is a valid MaxMind DB file.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\nif dummy_db_used:\n    print(f\"\\nNote: A dummy DB file was created and used. For actual results, replace '{DB_PATH}' with a real MaxMind DB file.\")\n    os.remove(DB_PATH) # Clean up dummy file\n","lang":"python","description":"This quickstart demonstrates basic usage of the `maxminddb` library, which `types-maxminddb` provides type hints for. To run this, you will need to have a MaxMind DB file (e.g., GeoLite2-City.mmdb) available. You can download free GeoLite2 databases from the MaxMind website. The code opens the database, performs an IP lookup, and iterates over a few entries. Ensure `MAXMIND_DB_PATH` is set or the database file is in the current directory."},"warnings":[{"fix":"Always install `maxminddb` alongside `types-maxminddb`.","message":"`types-maxminddb` is *only* type stubs and provides no runtime functionality. You *must* install the `maxminddb` library separately (e.g., `pip install maxminddb types-maxminddb`) for your application to run.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly update both `maxminddb` and `types-maxminddb`. If type-checking issues arise after a `maxminddb` update, check for newer `types-maxminddb` versions or specific `maxminddb` breaking changes.","message":"Type stubs are derived from the `maxminddb` library's API. If `maxminddb` changes its API (especially in minor or major versions), the `types-maxminddb` stubs might become outdated, leading to incorrect type-checking results until `typeshed` updates the stubs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always align your `types-maxminddb` version with your `maxminddb` runtime version. Consult the `maxminddb` changelog for breaking changes.","message":"While `types-maxminddb` itself doesn't typically have 'breaking' changes, significant API changes in the underlying `maxminddb` library (e.g., between `maxminddb` v2 and v3) will implicitly 'break' type compatibility if your `types-maxminddb` version targets an older API. `maxminddb` follows semantic versioning.","severity":"breaking","affected_versions":"Implicitly affected by `maxminddb` breaking changes (e.g., `maxminddb` 2.x to 3.x)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}