A free command line utility for MMDB files, maintained by InternetData. It works with any MMDB file, whoever built it, and needs no account or API key.
With it you can:
- Read data for IPs in an MMDB file.
- Import data in non-MMDB format into MMDB.
- Export data from MMDB format into non-MMDB format.
- See the difference between two MMDB files.
- Print the metadata of an MMDB file.
- Check that an MMDB file is not corrupted or invalid.
brew trust internetdata/tap
brew tap internetdata/tap
brew install mmdbHomebrew won't load a formula from a third-party tap until you trust it. Skip that first line and it fails with invalid syntax in tap!, which is misleading: the formula is fine. brew trust arrived in Homebrew 7, so run brew update first if it comes back as an unknown command. The same three lines work with Homebrew on Linux.
mmdb needs macOS 13 Ventura or later.
Install from our apt repository, which keeps mmdb up to date with apt upgrade:
echo "deb [trusted=yes] https://apt.internetdata.io/mmdb/ /" | sudo tee /etc/apt/sources.list.d/mmdb.list
sudo apt update && sudo apt install mmdbOr install a single .deb without the repository:
curl -Ls https://github.com/internetdata/mmdb/releases/latest/download/deb.sh | shchoco install mmdbOr install for the current user, which needs no admin rights:
iwr -useb https://github.com/internetdata/mmdb/releases/latest/download/windows.ps1 | iexdocker run --rm -v "$PWD:/data" -w /data ghcr.io/internetdata/mmdb metadata location.mmdbgo install github.com/internetdata/mmdb@latestBinaries are published for 23 platform and architecture pairs on the releases page. Pick yours:
# Linux amd64; for Windows use ".zip" instead of ".tar.gz"
curl -LO https://github.com/internetdata/mmdb/releases/download/v1.1.0/mmdb_1.1.0_linux_amd64.tar.gz
tar -xzf mmdb_1.1.0_linux_amd64.tar.gz
sudo mv mmdb /usr/local/bin/macOS has a one-line installer that picks the right architecture for you:
curl -Ls https://github.com/internetdata/mmdb/releases/latest/download/macos.sh | shNote that the binaries are not code-signed, so macOS Gatekeeper will ask before running one the first time, and Windows SmartScreen may warn.
git clone https://github.com/internetdata/mmdb
cd mmdb
./scripts/build.shThe result lands in build/. Go 1.27 or newer.
This will help you quickly get started with the mmdb CLI.
You can read from MMDB files in various different ways - as individual IPs, CIDRs or IP ranges, coming from the command line as arguments, or from files, or from stdin.
Pretty JSON format:
$ mmdb read -f json-pretty 8.8.8.8 location.mmdb
{
"city": "Mountain View",
"country": "US",
"geoname_id": "5375480",
"latitude": "37.4056",
"longitude": "-122.0775",
"postalcode": "94043",
"region": "California",
"timezone": "America/Los_Angeles"
}CSV format:
$ mmdb read -f csv 8.8.8.8 location.mmdb
ip,city,country,geoname_id,latitude,longitude,postalcode,region,timezone
8.8.8.8,Mountain View,US,5375480,37.4056,-122.0775,94043,California,America/Los_AngelesTSV format:
$ mmdb read -f tsv 8.8.8.8 location.mmdb
ip city country geoname_id latitude longitude postalcode region timezone
8.8.8.8 Mountain View US 5375480 37.4056 -122.0775 94043 California America/Los_AngelesVia a file:
$ cat ips.txt
8.8.8.8
8.8.8.0/31
8.8.8.0-8.8.8.1
8.8.8.0,8.8.8.1
$ mmdb read ips.txt location.mmdb | sort -u
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Via stdin:
$ echo 8.8.8.8 | mmdb read location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Multiple inputs are also possible - these all return the same thing:
$ echo -e '8.8.8.8\n1.2.3.4' | mmdb read location.mmdb
$ mmdb read 8.8.8.8 1.2.3.4 location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Brisbane","country":"AU","geoname_id":"2174003","latitude":"-27.48203","longitude":"153.01358","postalcode":"4101","region":"Queensland","timezone":"Australia/Brisbane"}Can check CIDRs and ranges - these will all return the same thing:
$ mmdb read 8.8.8.0/31 location.mmdb
$ mmdb read 8.8.8.0-8.8.8.1 location.mmdb
$ mmdb read 8.8.8.0,8.8.8.1 location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Importing allows taking in files as CSV/TSV/JSON, and outputting an MMDB file.
Importing is one of the most powerful/flexible features in mmdb. However, we only allow strings throughout the data at the current time.
See mmdb import --help for full details on usage.
Here are some basic examples:
# basic CSV importing into MMDB.
$ mmdb import --in data.csv --out data.mmdb
# generate MMDB from a TSV file containing IPv4 data.
$ cat data.tsv | mmdb import --ip 4 --tsv --out data.mmdb
# don't include the implicit `network` field in the output MMDB:
$ mmdb import --no-network --in data.csv --out data.mmdb
# size a build before running it: its nodes, records, fit and memory.
$ mmdb import --dry-run --no-network --in data.csv --out data.mmdb
# generate an MMDB without any fields, just IP ranges that meet a criteria.
$ mmdb import \
--size 24 --no-fields --ip 4 \
--in anycast.csv --out anycast.mmdbExporting allows taking in an MMDB file and outputting CSV/TSV/JSON.
See mmdb export --help for full details on usage.
A network holding a single address is written without its prefix length, as
8.8.8.8 rather than 8.8.8.8/32. Pass --cidr-only to always get CIDR form.
# basic export.
$ mmdb export data.mmdb data.csv
# basic export without a header.
$ mmdb export --no-header data.mmdb data.csv
# just see the number of entries it'd output.
$ mmdb export --no-header --format csv data.mmdb | wc -lYou can retrieve data in the metadata section of the MMDB file using the metadata subcommand.
Pretty format:
$ mmdb metadata location.mmdb
- Binary Format 2.0
- Database Type internetdata location.mmdb
- IP Version 4
- Record Size 32
- Node Count 123456789
- Description
en internetdata location.mmdb
- Languages en
- Build Epoch 123456789JSON format:
$ mmdb metadata -f json location.mmdb
{
"binary_format": "2.0",
"db_type": "internetdata location.mmdb",
"ip": 4,
"record_size": 32,
"node_count": 123456789,
"description": {
"en": "internetdata location.mmdb"
},
"languages": [
"en"
],
"build_epoch": 123456789
}You can verify if a MMDB file is correctly structured with the verify subcommand:
$ mmdb verify location.mmdb
validLet's force it to be invalid and check again:
$ cp location.mmdb location-tmp.mmdb
$ cat location.mmdb >> location-tmp.mmdb
$ mmdb verify location-tmp.mmdb
invalid: received decoding error (the MaxMind DB file's data section contains bad data (uint16 size of 11)) at offset of 13825601compress is only for legacy MMDB files: ones written without v2 of the Go
mmdbwriter, which mmdb is built on.
It stores each identical part of the search tree once, so the file shrinks and
every lookup answers as before. A file mmdb import writes never needs it, and
compress refuses a file that is compressed already.
$ mmdb compress legacy.mmdb compressed.mmdb
wrote compressed.mmdb: 8340464 -> 3083648 bytes (-63.0%)Auto-completion is supported for at least the following shells:
bash
zsh
fish
NOTE: it may work for other shells as well because the implementation is in Golang and is not necessarily shell-specific.
Installing auto-completions is as simple as running one command (works for bash, zsh and fish shells):
mmdb completion installIf you want to customize the installation process (e.g. in case the auto-installation doesn't work as expected), you can request the actual completion script for each shell:
# get bash completion script
mmdb completion bash
# get zsh completion script
mmdb completion zsh
# get fish completion script
mmdb completion fishIf your shell is not listed here, you can open an issue.
Note that as long as the COMP_LINE environment variable is provided to the binary itself, it will output completion results. So if your shell provides a way to pass COMP_LINE on auto-completion attempts to a binary, then have your shell do that with the mmdb binary itself (or any of our binaries).
All our CLIs respect either the --nocolor flag or the NO_COLOR environment variable to disable color output.
To enable color support for the Windows command prompt, run the following to enable Console Virtual Terminal Sequences.
REG ADD HKCU\CONSOLE /f /v VirtualTerminalLevel /t REG_DWORD /d 1You can disable this by running the following:
REG DELETE HKCU\CONSOLE /f /v VirtualTerminalLevelTo download InternetData's own databases, MMDB included, use the InternetData CLI or one of our client libraries for PHP, Python, Go, Java, Ruby and more. See our GitHub at https://github.com/internetdata for all of them.
Geolocation, anonymity, ownership and network databases for IP addresses and AS numbers, licensed as files you download and query yourself.
This project is licensed under the GNU General Public License v3.0.