MaxMindDB

A Swift reader for MaxMind DB (.mmdb) files — GeoLite2, GeoIP2, and anything else in the same format — wrapping a vendored copy of MaxMind's own libmaxminddb. It has no external or system-library dependencies.

import MaxMindDB

let city = try MaxMindDatabase(contentsOfFile: "/…/GeoLite2-City.mmdb")
print(city.metadata)               // GeoLite2-City built 2026-07-22 · IPv6 · 3 458 217 nodes

if let entry = try city.lookup("104.18.32.47") {
  try entry.string("country", "iso_code")       // "US"
  try entry.string("city", "names", "en")       // "San Francisco"
  try entry.double("location", "latitude")      // 37.7749
  entry.network                                 // "104.18.32.0/20"
}

What is here

Type
MaxMindDatabase	An open, memory-mapped database. Sendable; lookups need no serialisation.
MaxMindEntry	One record and the network it matched. Reads fields by path.
MaxMindValue	The format's full value tree, with accessors for the common cases.
MaxMindMetadata	Edition, build date, IP version, languages, node count.
IPAddress	A strict IPv4/IPv6 literal parser, and whether an address is globally routable.
MaxMindError	Everything that can go wrong, as Swift errors.

Installation

Add swift-mmdb to your package dependencies:

.package(url: "https://github.com/UInt8Co/swift-mmdb.git", from: "0.1.0")

Then add the MaxMindDB product to your target:

.product(name: "MaxMindDB", package: "swift-mmdb")

The Foundation package trait is enabled by default. It adds the MaxMindMetadata.buildEpoch Date property and LocalizedError conformance; the rest of the package does not depend on Foundation. To use the Foundation-free API, disable the dependency's default traits:

.package(
  url: "https://github.com/UInt8Co/swift-mmdb.git",
  from: "0.1.0",
  traits: []
)

MaxMindMetadata.buildEpochSeconds is available with either configuration.

Two things worth knowing

No hostname lookup is performed. MMDB_lookup_string is not wrapped. IPAddress parses literals in Swift and lookups go through MMDB_lookup_sockaddr, so there is no DNS-capable call in the lookup path. lookup(_: String) returns nil for anything that is not an address literal — a hostname is not an error, it is simply not a key.

IPAddress's parser is strict on purpose. It distinguishes address literals from hostnames without accepting ambiguous legacy syntax. It rejects inet_aton's short forms (10, 127.1), leading zeros, ports, brackets, zone identifiers and CIDR suffixes.

Building

Ordinary SwiftPM; no system dependencies.

swift build
swift test
# Verify the Foundation-free configuration too.
swift build --disable-default-traits

Sources/CMaxMindDB/README.md covers the vendored copy — what is upstream's, what is ours, and how to refresh it with Scripts/update-libmaxminddb.sh.

License

swift-mmdb is available under the MIT License. libmaxminddb is Apache-2.0 (Sources/CMaxMindDB/LICENSE-libmaxminddb). The test fixtures come from maxmind/MaxMind-DB, Apache-2.0 or MIT at your option; see Tests/MaxMindDBTests/Fixtures/README.md.

This package ships no GeoIP data. GeoLite2 databases are MaxMind's, downloaded by the user under their own account and licence.