# libmaxminddb: reading MaxMind DB files from C

> libmaxminddb is a small C library for resolving IP addresses against local MaxMind DB and GeoIP files. It gives you two build paths, an open format spec, and a hard requirement on POSIX.1-2001.

**maxmind/libmaxminddb** — C library for the MaxMind DB file format

- Repository: https://github.com/maxmind/libmaxminddb
- Website: https://maxmind.github.io/libmaxminddb/
- Stars: 1,027 · Forks: 246
- Language: C
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/maxmind-libmaxminddb

## The binary format is the real dependency

libmaxminddb exists because the MaxMind DB file format is not something every runtime reads natively. The README calls it a custom binary format designed to facilitate fast lookups of IP addresses while allowing great flexibility in the type of data associated with an address. Reading that layout by hand means implementing a binary search over a tree of records and getting the pointer arithmetic exactly right, which is the kind of work that is cheap to get almost working and expensive to get wrong under load.

The library takes that work off your plate and leaves you with an API for opening a file and resolving an address. The audience is therefore people writing network services in C or C++ who need to answer a geo or IP question on every request: firewall tooling, log processors, ad servers, abuse pipelines. It is not aimed at an analyst opening a GeoIP CSV in a spreadsheet, and it is not a geolocation service. It answers questions about addresses, from a file you host yourself, with no network call in the middle.

## Autotools from a named release tarball

Download the named libmaxminddb-*.tar.gz from the Releases page, unpack it, and build with the standard autotools sequence. These are the commands the README gives, run in that order from the unpacked source directory:

```bash
./configure
make
make check
sudo make install
sudo ldconfig
```

The configure script takes the standard options for setting where files are installed, such as --prefix, and ./configure --help lists the details. The README says you can skip make check, and in the same breath says it is always good to know the tests are passing on your platform, which is the reason to keep the step in a CI image rather than dropping it.

On compilers, the README states the code is known to work with GCC 4.4+ and clang 3.2+. It should also work with other compilers supporting C99, POSIX.1-2001, and the -fms-extensions flag or equivalent, which is needed to allow an anonymous union in a structure. That is a portability floor to check before you promise this builds on an embedded toolchain of your own.

## CMake covers Windows where autotools stalls

The project also ships a CMake build script. The README says it is primarily targeted at Windows users, but it can be used in other circumstances where the Autotools script does not work. The sequence is short:

```bash
cmake -B build
cd build/
cmake --build .
ctest -V .
cmake --build . --target install
```

The build tree is configured separately from the source directory, the test suite runs through ctest with verbose output so failures are visible in logs, and the install step reuses the same build system rather than a separate install target. Visual Studio users have a switch for the static CRT, which matters when the host application already links one CRT:

```bash
cmake -DMSVC_STATIC_RUNTIME=ON -DBUILD_SHARED_LIBS=OFF ..
```

There is also an uninstall target, cmake --build . --target uninstall. For teams that ship the library inside a product image, that target is the clean way to remove it again.

## The libmaxminddb.so.0 loader error after install

Even after a successful install you can hit an error saying libmaxminddb.so.0 is missing. That is a loader configuration problem rather than a build failure, and the README addresses it directly: you may need to add the lib directory in your prefix to your library path. On most Linux distributions, using the default prefix of /usr/local, the fix is:

```bash
sudo sh -c "echo /usr/local/lib  >> /etc/ld.so.conf.d/local.conf"
ldconfig
```

The broader point is that installing into a custom prefix with --prefix and then running ldconfig without registering that directory leaves you with a binary linked against a shared object the dynamic loader will not search for. In containers and CI images, adding the ld.so.conf.d entry early costs one line and saves a confusing failure at deploy time, where the error surfaces as a runtime abort rather than a build error.

## Ubuntu PPA and macOS package managers

MaxMind provides a PPA for recent Ubuntu versions. To add it to your APT sources:

```bash
sudo add-apt-repository ppa:maxmind/ppa
```

Then install the packages:

```bash
sudo apt update
sudo apt install libmaxminddb0 libmaxminddb-dev mmdb-bin
```

The runtime package, the development package, and the mmdb-bin command line tool all come from the same PPA, so a managed fleet can pin versions there instead of compiling on every host. On macOS the README points to Homebrew with brew install libmaxminddb, or to MacPorts with sudo port install libmaxminddb. Windows has no package manager path described here, which is exactly why the CMake build exists.

Note the split between the library and mmdb-bin. The library is the thing you link; mmdb-bin is a separate command line package that lets you query a database file without writing any code.

## Writing your own reader instead of linking the library

The alternative to linking libmaxminddb is to write your own reader for the MaxMind DB format. The format is openly specified, and the README states the spec is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License, so implementing the layout yourself is permitted. The difference in approach is where the effort lands. The spec gives you the tree structure, the record layout, and the pointer rules to implement. The library gives you an API that hides the tree traversal, the data pointer decoding, and the per-value type dispatch, and returns decoded values to you.

The README describes the format as built for fast lookups of IP addresses, which tells you the traversal pattern is the part worth inheriting rather than rewriting. If you need to attach your own record types, or you are chasing the last allocation in a hot loop, doing it yourself is plausible. If you simply need answers about addresses, the library exists so that you do not have to.

## Apache-2.0 for the code, CC BY-SA 3.0 for the format

Two licences sit inside this project and they are not the same. The library code is licensed under the Apache License, Version 2, with a copyright line reading Copyright 2013-2026 MaxMind, Inc. The format specification carries the Creative Commons Attribution-ShareAlike 3.0 Unported License, which is separate from the licence on the library code.

The repository is not archived, and the last push was on 2026-10-19. Recent releases are 1.14.1 on 2026-09-17, 1.14.0 on 2026-09-08, and 1.13.3 on 2026-03-05. Upgrading means replacing the installed library and relinking anything built against it. The tree carries Changes.md, doc/, include/, src/, bin/, and t/, so the release notes and the public headers are where you confirm what changed between versions instead of inferring it from the tag name.

## Conclusion

libmaxminddb fits C and C++ services that must resolve IP addresses against a local MaxMind DB file without a network round trip, including log processors and firewall tooling, and the Apache-2.0 terms make linking it into a commercial product straightforward. It is the wrong choice for teams that need a managed geolocation service, for languages with no binding to it, or for anyone unwilling to own a compiled dependency. Before committing, confirm the database you need exists in this format, build with make check so you know the suite passes on your platform, and make sure the libmaxminddb.so.0 loader path is configured for your deployment.

## FAQ

### What file format does libmaxminddb read?

It reads MaxMind DB files, including the GeoIP databases from MaxMind. The format is a custom binary format built for fast IP lookups, and the specification is published separately at maxmind.github.io/MaxMind-DB/.

### How do I install libmaxminddb on Ubuntu?

MaxMind publishes a PPA at ppa:maxmind/ppa, and libmaxminddb0, libmaxminddb-dev, and mmdb-bin are installable from it after running sudo apt update. You can also build from the named release tarball with the autotools sequence.

### Do I need automake and autoconf to build libmaxminddb?

Only when you build from a GitHub source archive or a clone of the Git repo. The README says that path also requires automake, autoconf, and libtool on top of make and a compiler, and that the clone must be recursive.

### Is libmaxminddb still maintained?

The repository is not archived, and the last push was on 2026-10-19. The releases listed are 1.14.1 on 2026-09-17, 1.14.0 on 2026-09-08, and 1.13.3 on 2026-03-05.

## Sources

- [License: Apache-2.0](https://github.com/maxmind/libmaxminddb/blob/main/LICENSE)
- [maxmind/libmaxminddb on GitHub](https://github.com/maxmind/libmaxminddb)
- [Project website](https://maxmind.github.io/libmaxminddb/)
- [README](https://github.com/maxmind/libmaxminddb/blob/main/README.md)
- [Releases](https://github.com/maxmind/libmaxminddb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/maxmind-libmaxminddb