NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #834 most downloaded on PyPI
Reader for the MaxMind DB format
Latest stable
3.3.0
Last release 5 days ago
17 Nov 2026
Ships fairly regularly
a new release about every 3 months
Nearly every release is documented
notes for 46 of 46 stable releases
1 version withdrawn
withdrawn after publishing
13 years old
47 releases · first in 2013
Drag across the ruler to compare, or tap a release to open it.
Fixed iteration over an IPv6 database with a network shorter than /96 whose first bits are zero, such as ::/1 . The readers raised ValueError or skipp
Fixed iteration over an IPv6 database with a network shorter than /96
whose first bits are zero, such as ::/1. The readers raised
ValueError or skipped networks. The pure Python reader also raised
ValueError for a network that starts at ::1:0:0, such as
::1:0:0/96.
The pure Python reader now raises InvalidDatabaseError for a search tree
record that points before the data section. Previously, it returned an
empty map.
Iterating over a database with a corrupt search tree, such as one with a
cycle, now raises InvalidDatabaseError. Previously, the C extension
could corrupt memory, and the pure Python reader raised RecursionError
or returned part of the networks.
A second __init__ on a pure Python Reader now closes the old
database, and an iterator from before it raises ValueError, as in the
C extension. Before, the iterator walked the new database with node
numbers from the old one. A failed __init__ keeps the old database.
After close(), an iterator raises ValueError in every mode.
The pure Python reader now raises InvalidDatabaseError when a value,
search tree record or pointer goes past the end of the data section, or when
the search tree overlaps the metadata. Previously, it could return a shorter
or wrong value, or decode bytes from the metadata section.
The pure Python reader now raises InvalidDatabaseError when a record map
key is not a string, as the C extension does. Previously, it returned the
non-string key or raised TypeError.
The pure Python reader now raises InvalidDatabaseError for extended type
byte 0. Previously, it decoded the value as a map. The C extension still
decodes it as a map, because libmaxminddb does not check this byte.
An empty database file now raises InvalidDatabaseError in MODE_FILE,
as in MODE_MEMORY. Previously, it raised OSError on platforms with
os.pread.
C extension:
Metadata, Reader andInvalidDatabaseError.uint32 values, which came back negative on platformslong, such as Windows.__init__ on aReader now closes the old database, and an iterator from before itValueError. A failed __init__ keeps the old database.Metadata changes nothing.RuntimeWarning or RuntimeError on free-threaded Python onReader failed to open or was used without __init__.Reader was closedStopIteration after its ReaderValueError.node_byte_size and search_tree_size properties toMetadata, as the pure Python Metadata has.Metadata:
TypeError. It raises InvalidDatabaseError for a missing key,ip_version or format version, abuild_epoch of 0, or a string that is not UTF-8 anywhere in theTypeError or UnicodeDecodeError.Reader.metadata() crashed with a segmentation fault on any unknownInvalidDatabaseErrorReader.metadata() has the UnicodeDecodeError as itsAdded maxminddb.Mode, which the README already described.
Type checkers now reject a subscript of maxminddb.types.Record or
Primitive, such as Record[str]. The subscript still works at
runtime. Pull request by Adam Hitchcock. GitHub #464.
Type hints:
Primitive includes bytearray, which the C extension returns forbytes type.Reader.__iter__ declares its item type.StrOrBytesPath and DatabaseSource aliases tomaxminddb.types.maxminddb.extension.Reader stub accepts only a path, as theMODE_FD accepts any object whose read() method returns bytes,gzip.GzipFile. maxminddb.types.SupportsRead describesMODE_AUTO now accepts a binary file object. Previously, it raised
TypeError. It reads the file object into memory with the pure Python
reader, as MODE_FD does. The C extension needs a path, so lookups are
slower than with a path when the extension is installed.
The pure Python reader raises TypeError when the database argument does
not suit the mode.
Updated the vendored libmaxminddb to 1.14.1. This fixes a build failure
with -Werror on platforms where ssize_t is 32 bits, such as i686.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Added limits to pure Python record and metadata decoding to prevent denial of service from crafted databases: 65,536 values, 512 nesting levels, and 2
InvalidDatabaseError. CPython may reach its recursion limit earlier,IndexError or struct.errorInvalidDatabaseError.The vendored libmaxminddb has been updated to 1.13.3. This includes a fix for the validation of empty maps and arrays at the end of the metadata secti
libmaxminddb has been updated to 1.13.3. This includes
a fix for the validation of empty maps and arrays at the end of the
metadata section. Previously, the extension would incorrectly reject
databases where a 0-element map or array was the last field in metadata.
Reported in vimt/MaxMind-DB-Writer-python#16.The vendored libmaxminddb has been updated to 1.13.1. This includes several security hardening improvements when reading corrupt or malicious database
libmaxminddb has been updated to 1.13.1. This includes
several security hardening improvements when reading corrupt or malicious
database files, including fixes for integer overflows, bounds checking, and
use-after-free prevention.IMPORTANT: Python 3.10 or greater is required. If you are using an older version, please use an earlier release.
MODE_FD. Pull request by Emanuel
Seemann. GitHub #234.maxminddb.reader.Metadata class has been
converted to a frozen dataclass. The __repr__ format has changed from
maxminddb.reader.Metadata(...) to Metadata(...). More importantly,
all Metadata attributes are now readonly and cannot be modified after
creation. If you were modifying metadata attributes after object creation,
you will need to update your code. All functionality remains the same,
including the node_byte_size and search_tree_size properties. Note:
The C extension's Metadata class has always been readonly, so this change
brings the pure Python implementation into consistency with the C extension.IntEnum (maxminddb.const.Mode).
The old constants (MODE_AUTO, MODE_FILE, etc.) remain available for
backward compatibility and are now aliases to the enum members. This provides
better IDE support and type safety while maintaining full backward
compatibility. You can now use either Mode.FILE or MODE_FILE - both
work identically. Since IntEnum is int-compatible, existing code using
the constants will continue to work without modification.Pyodide binary wheels will no longer be built by default. It is not possible to upload these to PyPI currently. We may consider reenabling them and pu
When upgrading to cibuildwheel 3.0.0, we inadvertently changed the artifact names, causing the wheels to not be uploaded to PyPI. This release fixes t
cibuildwheel 3.0.0, we inadvertently changed the artifact
names, causing the wheels to not be uploaded to PyPI. This release fixes that.
There are no other code changes. Report by David Hotham. GitHub #225.Python 3.14 is now officially supported, including binary wheels.
IMPORTANT: Python 3.9 or greater is required. If you are using an older version, please use an earlier release.
libmaxminddb has been updated to 1.12.2.The vendored libmaxminddb has been updated to 1.12.0. This fixes a memory leak when opening a database fails.
libmaxminddb has been updated to 1.12.0. This fixes a
memory leak when opening a database fails.The vendored libmaxminddb has been updated to 1.10.0. This fixes a bug that would cause incorrect results on databases that had search trees greater t
libmaxminddb has been updated to 1.10.0. This fixes aThis release includes no source code changes. The only changes are to the release workflow.
Added type annotations for instance variables on Metadata
Metadatamaxminddb.extension.setuptools is no longer listed as a runtime dependency. Pull request
by Lewis Collard. GitHub #155.The vendored libmaxminddb version was updated to 1.9.0. This fixes an issue when reading databases with a search tree exceeding 2 GB. Reported by Sami
libmaxminddb version was updated to 1.9.0. This fixes
an issue when reading databases with a search tree exceeding 2 GB.
Reported by Sami Salonen. GitHub #146.This is a re-release of 2.5.0 to address missing files from the sdist. Reported by Lumír 'Frenzy' Balhar. GitHub #132.
IMPORTANT: Python 3.8 or greater is required. If you are using an older version, please use an earlier release.
Reader class now implements the __iter__ method. This will
return an iterator that iterates over all records in the database,
excluding repeated aliased of the IPv4 network. Requested by
Jean-Baptiste Braun and others. GitHub #23.fork. This allows it
to run successfully on macOS. Pull request by Theodore Ni. GitHub #116.libmaxminddb will now be used by default when
building the extension. If you wish to continue using the system shared
library, you may set the MAXMINDDB_USE_SYSTEM_LIBMAXMINDDB environment
variable to a true value when building the extension.Package metadata was migrated from setup.py to setup.cfg. GitHub
setup.py to setup.cfg. GitHub
#113.IMPORTANT: Python 3.7 or greater is required. If you are using an older version, please use an earlier release.
distutils is no longer used for building the C extension.Py_INCREF was added to module initialization for the C
extension. Pull request by R. Christian McDonald. GitHub #106.The return type for maxminddb.open_database() has been simplified to be just the Reader class as opposed to a union of that with the extension class.
maxminddb.open_database() has been simplified
to be just the Reader class as opposed to a union of that with
the extension class. This is done by casting the extension to
Reader. The extension class has the same public API as the
pure Python implementation. This simplifies type checking for users of
this library. The Reader class is exposed as maxminddb.Reader.
Pull request by wouter bolsterlee. GitHub #88.maxminddb.__all__ is now set to define a public API. Pull request
by wouter bolsterlee. GitHub #88.repr output of maxminddb.reader.Metadata
in 2.1.0.The C extension now correctly supports objects that implement the os.PathLike interface.
os.PathLike interface.OSError subclass will now be thrown.Metadata class object is now available from the C extension
module as maxminddb.extension.Metadata rather than
maxminddb.extension.extension.maxminddb.extension.The 2.0.0 release unintentionally required Python to be compiled with mmap support for the module to work. mmap is now optional again. Reported by joh
mmap support for the module to work. mmap is now optional
again. Reported by john-heasman-cg. GitHub #76.Added py.typed file per PEP 561. Reported by Árni Már Jónsson.
py.typed file per PEP 561. Reported by Árni Már Jónsson.Fix minimum required python version in setup.py. Pull request by Boros Gábor. GitHub #69 & #70.
setup.py. Pull request by
Boros Gábor. GitHub #69 & #70.IMPORTANT: Python 3.6 or greater is required. If you are using an older version, please use a 1.x.x release.
1.5.3 was missing a test database. This release adds the test file. There are no other changes. Reported by Lumír 'Frenzy' Balhar. GitHub #60.
Fix a segfault when decoding a database with a corrupt data section. Reported by Robert Scott. GitHub #58.
Minor performance improvements in the pure Python reader.
Fix a possible segfault due to not correctly incrementing the reference on a returned object.
Python 3.3 and 3.4 are no longer supported.
ImportWarning
when importing the module on Python 2 with -Wdefault set. Reported by
David Szotten and Craig de Stigter. GitHub #31.get method now accepts ipaddress.IPv4Address and
ipaddress.IPv6Address objects in addition to strings. This works with
both the pure Python implementation as well as the extension. Based on a
pull request #48 by Eric Pruitt. GitHub #50.get_with_prefix_len, was added. This method returns a
tuple containing the record and the prefix length.Fix test failure on Python 3.7. Reported by Carl George. GitHub #35.
IMPORTANT: Previously, the pure Python reader would allow ipaddress.IPv4Address and ipaddress.IPv6Address objects when calling .get(). This would fail
ipaddress.IPv4Address and ipaddress.IPv6Address objects when calling
.get(). This would fail with the C extension. The fact that these objects
worked at all was an implementation detail and has varied with different
releases. This release makes the pure Python implementation consistent
with the extension. A TypeError will now be thrown if you attempt to
use these types with either the pure Python implementation or the
extension. The IP address passed to .get() should be a string type.maxminddb.Reader object using MODE_FD.
This will read the database from the file descriptor into memory. Pull
request by nkinkade. GitHub #33.maxminddb.Reader and the C extension now support being used in a context manager. Pull request by Joakim Uddholm. GitHub #21 & #28.
maxminddb.Reader and the C extension now support being used in a context
manager. Pull request by Joakim Uddholm. GitHub #21 & #28.MODE_MMAP_EXT is requested but
the C extension is not available.Improve compatibility with other Python 2 ipaddress backports. Although ipaddress is highly recommended, py2-ipaddress and backport_ipaddress should n
ipaddress backports. Although
ipaddress is highly recommended, py2-ipaddress and
backport_ipaddress should now work. Incompatibility reported by
John Zadroga on geoip2 GitHub issue #41.Fix to the classifiers in setup.py. No code changes.
setup.py. No code changes.This module now uses the ipaddress module for Python 2 rather than the ipaddr module. Users should notice no behavior change beyond the change in depe
ipaddress module for Python 2 rather than the
ipaddr module. Users should notice no behavior change beyond the change
in dependencies.requirements.txt from MANIFEST.in in order to stop warning
during installation.Previously if MODE_FILE was used and the database was loaded before forking, the parent and children would use the same file table entry without locki
MODE_FILE was used and the database was loaded before
forking, the parent and children would use the same file table entry without
locking causing errors reading the database due to the offset being changed
by other processes. In MODE_FILE, the reader will now use os.pread
when available and a lock when os.pread is not available (e.g., Python
2). If you are using MODE_FILE on a Python without os.pread, it is
recommended that you open the database after forking to reduce resource
contention.Metadata class now overloads __repr__ to provide a useful
representation of the contents when debugging.InvalidDatabaseError will now be thrown if the data type read from
the database is invalid. Previously a KeyError was thrown.On Python 3 there was a potential issue where open_database with MODE_AUTO would try to use the C extension when it was not available. This could caus
open_database with
MODE_AUTO would try to use the C extension when it was not available.
This could cause the function to fail rather than falling back to a pure
Python mode.The pure Python reader now supports an optional file and memory mode in addition to the existing memory-map mode. If your Python does not provide the
mmap module, the file mode will be used by default.open_database
function in maxminddb. This function now takes an optional read
mode.InvalidDatabaseError class
and instead uses the one defined in maxminddb.errors.Two potential C extension issues discovered by Coverity were fixed:
Corrected initialization of objects in C extension and made the objects behave more similarly to their pure Python counterparts.
Switched to Apache 2.0 license.
Fixed packaging problem that caused import to fail.
import to fail.This release includes a pure Python implementation of the database reader. If libmaxminddb is not available or there are compilation issues, the modul
libmaxminddb is not available or there are compilation issues, the
module will fall-back to the pure Python implementation.Removed -Werror compiler flag as it was causing problems for some OS X users.
Refactored code and fixed a memory leak when throwing an exception.
* Added MANIFEST.in
Added MANIFEST.in
* Initial release
Initial release
One column per quarter.