{"id":9950,"library":"mmdb-writer","title":"mmdb-writer Library","description":"mmdb-writer is a Python library for creating MaxMind DB (.mmdb) format files, which can be efficiently read by MaxMind's official client libraries in various programming languages. It allows users to associate custom data with IP address ranges (IPv4 and IPv6). The current version is 0.2.6, with updates released periodically, though not on a fixed schedule.","status":"active","version":"0.2.6","language":"en","source_language":"en","source_url":"https://github.com/vimt/MaxMind-DB-Writer-python","tags":["MaxMind","MMDB","IP","geolocation","database","network"],"install":[{"cmd":"pip install mmdb-writer","lang":"bash","label":"Install mmdb-writer"}],"dependencies":[{"reason":"Required for interacting with the MaxMind DB format internally.","package":"maxminddb"},{"reason":"Required for robust handling and parsing of IP network addresses.","package":"netaddr"}],"imports":[{"symbol":"MMDBWriter","correct":"from mmdb_writer import MMDBWriter"}],"quickstart":{"code":"import os\nfrom mmdb_writer import MMDBWriter\nfrom netaddr import IPNetwork # Optional, strings also accepted by insert_network\n\n# Define the output database file\noutput_file = 'my_ip_database.mmdb'\n\n# Initialize the writer\n# ip_version: 4 for IPv4 only, 6 for mixed IPv4/IPv6.\n# database_type: An arbitrary string to identify your database.\n# record_size: Affects max data size per IP entry (e.g., 24 for ~1.5KB, 32 for ~6KB).\nwriter = MMDBWriter(\n    ip_version=6,\n    database_type='Custom-Geo-Database',\n    languages=['en', 'es'],\n    description={'en': 'My custom IP lookup database', 'es': 'Mi base de datos IP personalizada'},\n    record_size=24, # Recommended for many common use cases\n    store_ipv4_in_ipv6_format=True # Recommended when ip_version is 6\n)\n\n# Insert individual networks with associated data\n# Data can be a dictionary, list, string, int, float, or boolean.\nwriter.insert_network('1.1.1.0/24', {'country': 'US', 'city': 'Exampleville', 'latitude': 34.05, 'longitude': -118.25})\nwriter.insert_network('2.2.2.0/24', {'country': 'CA', 'isp': 'InternetCorp'})\n\n# Insert a list of networks with the same data\n# Can use strings directly or netaddr.IPNetwork objects.\nnetworks_for_region = [\n    '3.3.3.0/28',\n    IPNetwork('3.3.3.16/28') # Both strings and IPNetwork objects are fine here\n]\nwriter.insert_network_list(networks_for_region, {'country': 'UK', 'continent': 'Europe', 'timezone': 'Europe/London'})\n\n# Insert an IPv6 network\nwriter.insert_network('2001:db8::/32', {'country': 'DE', 'organization': 'TechSolutions GmbH'})\n\n# Close the writer to finalize and write the database file\nwriter.close(output_file)\n\nprint(f\"MMDB database '{output_file}' created successfully.\")\n\n# Clean up the created file (uncomment if you want to remove it automatically)\n# os.remove(output_file)","lang":"python","description":"This quickstart demonstrates how to initialize `MMDBWriter`, insert IPv4 and IPv6 networks with various data types, and finalize the database creation. It highlights the use of `insert_network` for single entries and `insert_network_list` for multiple, sharing data. Key parameters like `ip_version`, `database_type`, and `record_size` are explained."},"warnings":[{"fix":"Ensure your data dictionary/list structure is consistent across all insertions for common keys. Design your data payload carefully so that a specific key path (e.g., `data['key1']['key2']`) always resolves to the same MaxMind DB data type (e.g., always a string, always a map, always an integer).","message":"MaxMind DBs enforce strict data type consistency for any given key path across all records. If you insert `{'location': 'US'}` for one IP and later `{'location': {'country': 'US'}}` for another, official MaxMind readers might fail or produce unexpected results due to schema inconsistency.","severity":"gotcha","affected_versions":"All versions of mmdb-writer (due to MaxMind DB specification)"},{"fix":"Always pass `store_ipv4_in_ipv6_format=True` to the `MMDBWriter` constructor when `ip_version` is 6.","message":"When `ip_version` is set to 6 (to support both IPv4 and IPv6), it is highly recommended to set `store_ipv4_in_ipv6_format=True`. Failing to do so can result in larger database files and potentially slower lookups for mixed-format databases.","severity":"gotcha","affected_versions":"All versions of mmdb-writer"},{"fix":"Estimate the maximum size of your data dictionary per IP network. Use `record_size=24` for small data (~1.5KB), `record_size=28` for medium (~4.5KB), and `record_size=32` for larger payloads (~6KB). Refer to MaxMind DB documentation for more details on `record_size`.","message":"Choosing an appropriate `record_size` is crucial. It determines the maximum size of data that can be associated with a single IP network. Values like 24, 28, or 32 are common, with higher values supporting larger data payloads but potentially increasing file size and lookup times slightly.","severity":"gotcha","affected_versions":"All versions of mmdb-writer"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the package using `pip install mmdb-writer`.","cause":"The `mmdb-writer` package is not installed in the current Python environment or the environment is not activated.","error":"ModuleNotFoundError: No module named 'mmdb_writer'"},{"fix":"Ensure the user executing the script has write access to the target directory. Consider writing to a user-specific directory (e.g., `~/my_database.mmdb`) or a temporary directory (e.g., `/tmp/my_database.mmdb` on Unix-like systems) if permissions are restricted.","cause":"The Python process does not have the necessary write permissions for the specified output directory or file path where it's attempting to create the `.mmdb` file.","error":"Permission denied: 'my_database.mmdb' (or similar OSError)"},{"fix":"Carefully review your input data for type consistency. For any specific key or nested key path (e.g., `data['location']['city']`), ensure that the associated data type (string, integer, map, list, etc.) is uniform across all records inserted into the database.","cause":"This error most commonly indicates that the database schema is inconsistent. `mmdb-writer` allows flexible data insertion, but if the data types for a given key path differ across various IP ranges (e.g., `data['key']` is a string for one IP and a dictionary for another), the resulting `.mmdb` file violates the MaxMind DB specification.","error":"ValueError: The MaxMind DB file is invalid or corrupt. (Observed when reading with a `maxminddb` reader)"}]}