Java reader for the MaxMind DB format
Clone or download
andyjack Merge pull request #41 from maxmind/wes/patch-dependency
Upgrade `com.fasterxml.jackson.core:jackson-databind` artifact
Latest commit 3c32137 Oct 15, 2018

MaxMind DB Reader

Build Status Known Vulnerabilities


This is the Java API for reading MaxMind DB files. MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6).



We recommend installing this package with Maven. To do this, add the dependency to your pom.xml:



Add the following to your build.gradle file:

repositories {
dependencies {
    compile 'com.maxmind.db:maxmind-db:1.2.2'


Note: For accessing MaxMind GeoIP2 databases, we generally recommend using the GeoIP2 Java API rather than using this package directly.

To use the API, you must first create a Reader object. The constructor for the reader object takes a File representing your MaxMind DB. Optionally you may pass a second parameter with a FileMode with a value of MEMORY_MAP or MEMORY. The default mode is MEMORY_MAP, which maps the file to virtual memory. This often provides performance comparable to loading the file into real memory with MEMORY.

To look up an IP address, pass the address as an InetAddress to the get method on Reader. This method will return the result as a com.fasterxml.jackson.databind.JsonNode object. JsonNode objects are used as they provide a convenient representation of multi-type data structures and the databind package of Jackson 2 supplies many tools for interacting with the data in this format.

We recommend reusing the Reader object rather than creating a new one for each lookup. The creation of this object is relatively expensive as it must read in metadata for the file.


File database = new File("/path/to/database/GeoIP2-City.mmdb");
Reader reader = new Reader(database);

InetAddress address = InetAddress.getByName("");

JsonNode response = reader.get(address);




The database API supports pluggable caching (by default, no caching is performed). A simple implementation is provided by com.maxmind.db.CHMCache. Using this cache, lookup performance is significantly improved at the cost of a small (~2MB) memory overhead.


Reader reader = new Reader(database, new CHMCache());

Multi-Threaded Use

This API fully supports use in multi-threaded applications. In such applications, we suggest creating one Reader object and sharing that among threads.

Common Problems

File Lock on Windows

By default, this API uses the MEMORY_MAP mode, which memory maps the file. On Windows, this may create an exclusive lock on the file that prevents it from being renamed or deleted. Due to the implementation of memory mapping in Java, this lock will not be released when the DatabaseReader is closed; it will only be released when the object and the MappedByteBuffer it uses are garbage collected. Older JVM versions may also not release the lock on exit.

To work around this problem, use the MEMORY mode or try upgrading your JVM version. You may also call System.gc() after dereferencing the DatabaseReader object to encourage the JVM to garbage collect sooner.

Packaging Database in a JAR

If you are packaging the database file as a resource in a JAR file using Maven, you must disable binary file filtering. Failure to do so will result in InvalidDatabaseException exceptions being thrown when querying the database.


The MaxMind DB format is an open format for quickly mapping IP addresses to records. The specification is available as part of our Perl writer for the format.

Bug Tracker

Please report all issues with this code using the [GitHub issue tracker] (

If you are having an issue with a MaxMind database or service that is not specific to this reader, please [contact MaxMind support] (


MaxMind has tested this API with Java 6 and above.


Patches and pull requests are encouraged. Please include unit tests whenever possible.


The MaxMind DB Reader API uses Semantic Versioning.

Copyright and License

This software is Copyright (c) 2014 by MaxMind, Inc.

This is free software, licensed under the Apache License, Version 2.0.