Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/msimerson/maxmind-geolite-mirror/llms.txt

Use this file to discover all available pages before exploring further.

maxmind-geolite-mirror is a global CLI tool you install once with npm and then run on a schedule to keep MaxMind’s GeoLite2 IP geolocation databases current on your server. This guide walks you from zero to a fully populated /usr/local/share/GeoIP/ directory with all three .mmdb files downloaded and ready to use.
A valid MaxMind license key is required. If MAXMIND_LICENSE_KEY is not set and no key is present in config.js, the tool exits immediately with an error: missing license_key in .../config.js!. No databases will be downloaded without a key configured.
1

Get a MaxMind license key

GeoLite2 databases require a free MaxMind account. Register at maxmind.com/en/geolite2/signup, then generate a license key from the My License Key section of your account portal.Keep the key handy — you will set it as the MAXMIND_LICENSE_KEY environment variable in a later step.
2

Install the CLI

Install the package globally with npm. Node.js v14.0.0 or later is required.
npm install -g maxmind-geolite-mirror
This installs the maxmind-geolite-mirror binary to your global npm bin directory (typically /usr/local/bin/maxmind-geolite-mirror).
3

Create the database directory

The tool writes .mmdb files to /usr/local/share/GeoIP/ by default. Create the directory if it does not already exist:
mkdir -p /usr/local/share/GeoIP
Ensure the user that will run the tool has write permission to this directory.
4

Set the license key

Export your MaxMind license key as an environment variable in your current shell session:
export MAXMIND_LICENSE_KEY=your_key_here
Replace your_key_here with the license key you generated in step 1. To make this permanent, add the export line to your shell profile (e.g. ~/.bashrc, ~/.zshrc) or your system’s environment configuration.
5

Run the mirror

Execute the CLI to download all three GeoLite2 databases:
maxmind-geolite-mirror
The tool processes each database in series. For each file it checks whether a local copy already exists. If it does, a HEAD request with an If-Modified-Since header is sent to confirm whether the remote file is newer. If no local copy exists yet, the tool downloads immediately without a preliminary check. You will see output similar to:
downloading /usr/local/share/GeoIP/GeoLite2-Country.mmdb
downloading /usr/local/share/GeoIP/GeoLite2-City.mmdb
downloading /usr/local/share/GeoIP/GeoLite2-ASN.mmdb
On subsequent runs, if the databases are already current, the output will instead show:
/usr/local/share/GeoIP/GeoLite2-Country.mmdb is up-to-date
/usr/local/share/GeoIP/GeoLite2-City.mmdb is up-to-date
/usr/local/share/GeoIP/GeoLite2-ASN.mmdb is up-to-date
6

Verify the downloaded files

Confirm all three database files are present in the GeoIP directory:
ls -la /usr/local/share/GeoIP/
You should see output like:
-rw-r--r--  1 root  wheel   6081823 Jan 14 09:00 GeoLite2-ASN.mmdb
-rw-r--r--  1 root  wheel  69956199 Jan 14 09:00 GeoLite2-City.mmdb
-rw-r--r--  1 root  wheel   6322287 Jan 14 09:00 GeoLite2-Country.mmdb
All three files are standard MaxMind DB (.mmdb) binary files readable by any MaxMind-compatible library.

​
Downloaded files

After a successful run, your GeoIP directory contains the following files:
FileDescription
GeoLite2-Country.mmdbCountry-level geolocation data (country code, country name)
GeoLite2-City.mmdbCity-level geolocation data (city, subdivision, postal code, coordinates)
GeoLite2-ASN.mmdbAutonomous System Number and organization name for each IP range
If /usr/local/share/GeoIP is not writable by the user running the tool, set the MAXMIND_DB_DIR environment variable to a directory you do control:
export MAXMIND_DB_DIR=/home/example/maxmind-db
maxmind-geolite-mirror
The tool will read MAXMIND_DB_DIR at startup and write all database files to that path instead of the default.
Run maxmind-geolite-mirror on a weekly cron schedule to keep your databases automatically up-to-date. MaxMind publishes updated GeoLite2 databases every Tuesday, and the built-in If-Modified-Since check means the tool only downloads data when something has actually changed. See the Scheduling guide for ready-to-use cron job examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us