Skip to main content

MMDB CLI Installation

MMDB CLI ships as a single static binary. You can install it with Homebrew on macOS, Linux package managers, pre-built archives from GitHub Releases, a container image, or build from source.

Supported Platforms​

Pre-built binaries are published for the following OS and architecture combinations:

PlatformArchitectureSupported
Linuxamd64✅
Linuxarm64✅
macOSamd64✅
macOSarm64 (Apple Silicon)✅
FreeBSDamd64✅
FreeBSDarm64✅
Windowsamd64✅
Windowsarm64✅

Note: If your platform is not listed above, you can build MMDB CLI from source.

Note: A multi-arch container image (linux/amd64, linux/arm64) is also published to the GitHub Container Registry — see Installation (Docker).

Note: We mainly test MMDB CLI on Linux (amd64) and macOS (arm64). If you encounter issues on other platforms, please open an issue.

Linux packages

We also publish deb, rpm, apk, and Arch Linux packages. Download them from GitHub Releases.

Package FormatArchitectureSupported
debamd64✅
debarm64✅
rpmamd64✅
rpmarm64✅
apkamd64✅
apkarm64✅
Arch Linuxamd64✅
Arch Linuxarm64✅

Installation (macOS — Homebrew)​

On macOS, install MMDB CLI from the InfraZ Homebrew tap:

brew tap infraz/tap
brew install infraz/tap/mmdb-cli

Verify:

mmdb-cli version
macOS Gatekeeper

The Homebrew cask is not Apple-notarized. If macOS blocks the binary, remove the quarantine attribute:

xattr -dr com.apple.quarantine "$(which mmdb-cli)"

Installation (Docker)​

Container images are published to the GitHub Container Registry (GHCR) for linux/amd64 and linux/arm64. No registry login is required to pull public images.

docker pull ghcr.io/infraz/mmdb-cli:latest

Image tags​

TagPoints toMutable?
latestLatest commit on the main branchyes
X.Y.Z (e.g. 0.5.0)The matching vX.Y.Z releaseno
Pin a version for reproducible use

For CI and scripts, pin an immutable X.Y.Z release tag (or a digest, ghcr.io/infraz/mmdb-cli@sha256:...) rather than latest.

Running the image​

The image ENTRYPOINT is mmdb-cli and its working directory is /data. Mount the directory that holds your MMDB/JSON files at /data, then pass the subcommand and flags as usual:

# Show version (no mount needed)
docker run --rm ghcr.io/infraz/mmdb-cli:latest version

# Inspect an IP against a local database
docker run --rm -v "$PWD:/data" ghcr.io/infraz/mmdb-cli:latest \
  inspect -i GeoLite2-City.mmdb 8.8.8.8

# Print metadata as JSON
docker run --rm -v "$PWD:/data" ghcr.io/infraz/mmdb-cli:latest \
  metadata -i GeoLite2-City.mmdb -f json

Writing files back to the host​

The container runs as a non-root user (UID 1000). When a command writes output to the mounted directory, add --user so the new files are owned by you:

docker run --rm -v "$PWD:/data" --user "$(id -u):$(id -g)" \
  ghcr.io/infraz/mmdb-cli:latest \
  generate -i dataset.json -o custom.mmdb
SELinux hosts

On Fedora, RHEL, and derivatives, append :z (or :Z) to the volume so the bind mount is relabelled: -v "$PWD:/data:z".

Shell alias (optional)​

To use the container as if it were a locally installed binary:

alias mmdb-cli='docker run --rm -v "$PWD:/data" --user "$(id -u):$(id -g)" ghcr.io/infraz/mmdb-cli:latest'

mmdb-cli version
mmdb-cli verify -i GeoLite2-City.mmdb

Supply-chain metadata​

Every image is published with SLSA build provenance and an SBOM attestation. Inspect them with:

docker buildx imagetools inspect ghcr.io/infraz/mmdb-cli:latest

Installation Instructions (Linux Package Manager)​

Debian and Ubuntu​

  1. Resolve the latest version and architecture:
export MMDB_CLI_VERSION=$(curl -s https://api.github.com/repos/InfraZ/mmdb-cli/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
export ARCH=$(dpkg --print-architecture)
  1. Download the .deb package using curl or wget
curl -LO "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.deb"
  1. Install .deb package using apt
apt install ./mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.deb
  1. Verify the installation by running the following command.
mmdb-cli version

RH-based (RHEL, Fedora, CentOS, Rocky Linux, AlmaLinux)​

  1. Resolve the latest version:
export MMDB_CLI_VERSION=$(curl -s https://api.github.com/repos/InfraZ/mmdb-cli/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
  1. Install the .rpm package using yum or dnf
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH=amd64; [ "$ARCH" = "aarch64" ] && ARCH=arm64
dnf install "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.rpm"
  1. Verify the installation by running the following command.
mmdb-cli version

Alpine Linux​

  1. Resolve the latest version:
export MMDB_CLI_VERSION=$(curl -s https://api.github.com/repos/InfraZ/mmdb-cli/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/v//')
  1. Download the .apk package using curl or wget
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH=amd64; [ "$ARCH" = "aarch64" ] && ARCH=arm64
curl -LO "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.apk"
  1. Install .apk package using apk
apk add --allow-untrusted ./mmdb-cli_${MMDB_CLI_VERSION}_linux_${ARCH}.apk
  1. Verify the installation by running the following command.
mmdb-cli version

Installation Instructions (Pre-built Binary)​

Linux and macOS​

  1. Pick a version and platform from GitHub Releases:
export MMDB_CLI_VERSION=0.5.0
export MMDB_CLI_PLATFORM=linux_amd64   # e.g. darwin_arm64, freebsd_amd64
  1. Download the MMDB CLI tarball using curl, wget, or any other tool.
curl -LO "https://github.com/InfraZ/mmdb-cli/releases/download/v${MMDB_CLI_VERSION}/mmdb-cli_${MMDB_CLI_VERSION}_${MMDB_CLI_PLATFORM}.tar.gz"
  1. Extract the downloaded tarball.
tar -xzf mmdb-cli_${MMDB_CLI_VERSION}_${MMDB_CLI_PLATFORM}.tar.gz
  1. Move the extracted binary file to a directory in your $PATH.
mv mmdb-cli /usr/local/bin/
  1. Verify the installation by running the following command.
mmdb-cli version

FreeBSD​

Use the same tarball flow as Linux/macOS with a FreeBSD platform label, for example freebsd_amd64 or freebsd_arm64.

Windows​

  1. Download mmdb-cli_<version>_windows_<arch>.zip from GitHub Releases.
  2. Extract mmdb-cli.exe to a directory on your PATH.
  3. Open a new terminal and run:
mmdb-cli version