Install & Compatibility
Where this runs
tested against v0.2.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.126s · 27.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.119s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MMDBWriter
✓ from mmdb_writer import MMDBWriter
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.
import os
from mmdb_writer import MMDBWriter
from netaddr import IPNetwork # Optional, strings also accepted by insert_network
# Define the output database file
output_file = 'my_ip_database.mmdb'
# Initialize the writer
# ip_version: 4 for IPv4 only, 6 for mixed IPv4/IPv6.
# database_type: An arbitrary string to identify your database.
# record_size: Affects max data size per IP entry (e.g., 24 for ~1.5KB, 32 for ~6KB).
writer = MMDBWriter(
ip_version=6,
database_type='Custom-Geo-Database',
languages=['en', 'es'],
description={'en': 'My custom IP lookup database', 'es': 'Mi base de datos IP personalizada'},
record_size=24, # Recommended for many common use cases
store_ipv4_in_ipv6_format=True # Recommended when ip_version is 6
)
# Insert individual networks with associated data
# Data can be a dictionary, list, string, int, float, or boolean.
writer.insert_network('1.1.1.0/24', {'country': 'US', 'city': 'Exampleville', 'latitude': 34.05, 'longitude': -118.25})
writer.insert_network('2.2.2.0/24', {'country': 'CA', 'isp': 'InternetCorp'})
# Insert a list of networks with the same data
# Can use strings directly or netaddr.IPNetwork objects.
networks_for_region = [
'3.3.3.0/28',
IPNetwork('3.3.3.16/28') # Both strings and IPNetwork objects are fine here
]
writer.insert_network_list(networks_for_region, {'country': 'UK', 'continent': 'Europe', 'timezone': 'Europe/London'})
# Insert an IPv6 network
writer.insert_network('2001:db8::/32', {'country': 'DE', 'organization': 'TechSolutions GmbH'})
# Close the writer to finalize and write the database file
writer.close(output_file)
print(f"MMDB database '{output_file}' created successfully.")
# Clean up the created file (uncomment if you want to remove it automatically)
# os.remove(output_file)
mmdb-writer --version
Debug
Known issues
gotchaMaxMind 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.fixEnsure 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).
affects: All versions of mmdb-writer (due to MaxMind DB specification)
gotchaWhen `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.fixAlways pass `store_ipv4_in_ipv6_format=True` to the `MMDBWriter` constructor when `ip_version` is 6.
affects: All versions of mmdb-writer
gotchaChoosing 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.fixEstimate 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`.
affects: All versions of mmdb-writer
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mmdb_writer'
The `mmdb-writer` package is not installed in the current Python environment or the environment is not activated.
fixInstall the package using `pip install mmdb-writer`.
Permission denied: 'my_database.mmdb' (or similar OSError)
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.
fixEnsure 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.
ValueError: The MaxMind DB file is invalid or corrupt. (Observed when reading with a `maxminddb` reader)
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.
fixCarefully 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.
Upgrade
Version history
0.2.7latest on PyPI · released Jun 1, 2026
Audit
Dependencies
maxminddbrequiredRequired for interacting with the MaxMind DB format internally.
netaddrrequiredRequired for robust handling and parsing of IP network addresses.