Skip to content
Redistribution of MaxMind GeoLite2 databases as an npm lib
JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
redist Update redistribution (cron job 26.3) Feb 19, 2020
scripts Prevent HTTP errors from bubbling up Jan 24, 2020
test Add tests Jan 9, 2020
.gitignore Lint & fixes, working CI Jan 4, 2020
.npmignore Add CI scripts to .npmignore Jan 22, 2020
.travis.yml Add Travis CI cron job for mirror updates Jan 9, 2020
EULA new redistribution mechanism, updated license Jan 3, 2020
LICENSE Add TypeScript usage docs with response type Jan 23, 2020
index.js lint, clean git history Jan 21, 2020
package-lock.json Add TypeScript types Jan 23, 2020
package.json Bump to v1.0.4 Jan 24, 2020


Build Status NPM published version Node version Types Status Install size

MaxMind's GeoLite2 free databases as an npm library. As this is a redistribution, you don't need a MaxMind license key. However, additional restrictions apply, and while they should be transparent to most users, you should read this README and the LICENSE file carefully before deciding to use this.

You will need a database reader capable of reading .mmdb files, like node-maxmind, if you wish to use the data.

This package contains the 3 GeoLite2 databases, namely:

  • GeoLite2-ASN
  • GeoLite2-Country
  • GeoLite2-City

For more info check out the MaxMind website.

Due to license requirements, this package automatically updates the databases in the background when it detects that a new version is available.

See Warning section for more info.


Using the geoip data

Example geoip lookup, using the GeoLite2-City database with node-maxmind as a db reader:


const geolite2 = require('geolite2-redist');

const maxmind = require('maxmind');

(async () => {
  let lookup = await'GeoLite2-City', path => {

  let city = lookup.get('');

  // Call this when done to empty node's event loop


const geolite2 = require('geolite2-redist');

const maxmind = require('maxmind');
const fs = require('fs');

let lookup ='GeoLite2-City', path => {
  let buf = fs.readFileSync(path);
  return new maxmind.Reader(buf);

let city = lookup.get('');


Advanced usage

If you do not consume the databases directly, or need more flexible methods, the internal geolite2.UpdateSubscriber class is exposed so you can directly listen to database update events.

Example usage:

const geolite2 = require('geolite2-redist');

function useGeolite() {
  // You can retrieve the path to `.mmdb` files
  let cityPath = geolite2.paths['GeoLite2-City'];

const dbWatcher = new geolite2.UpdateSubscriber();
dbWatcher.on('update', () => {

// Empty event loop when shutting down

Usage with TypeScript

This package includes its own types and you can pass the response type in open:

import geolite2 from 'geolite2-redist';
import maxmind, { CityResponse } from 'maxmind';

(async () => {
  let lookup = await<CityResponse>('GeoLite2-City', path => {

  let city = lookup.get('');

  // Call this when done to empty node's event loop


Methods, databaseReader)

  • database: <string> One of GeoLite2-ASN, GeoLite2-Country, GeoLite2-City.
  • databaseReader: <function> a function that will build a database reader object (lookup). Must return a Promise or an <object>. Called with two arguments:
    • path: <string> The filesystem path to the database .mmdb file.
    • update: <boolean> Will be set to true if this is a rebuild following a database update. false on first run.


geolite2.paths <object>

Full fs paths for each database. Warning: you need to let the library update the databases automatically, see Usage section.

  • GeoLite2-ASN: <string>
  • GeoLite2-Country: <string>
  • GeoLite2-City: <string>



Internal class used to automatically update databases, exposed to allow advanced usage without the method - see Usage.

  • Constructor
    • new UpdateSubscriber() Returns EventEmitter instance
  • Events
    • checking Emitted when automatically checking for database updates.
    • downloading Emitted when an update has been found and the new databases are being downloaded in the background.
    • update Emitted when new databases have been written to the filesystem.
  • Methods
    • checkUpdates() Checks for new database updates and downloads them.
    • triggerUpdate() Replaces the current databases with fresh copies from the mirror.
    • close() Shuts down the updater.
  • Props
    • downloading: <boolean> Whether databases are being downloaded in the background right now - see downloading event.


Please carefully read the LICENSE and EULA files. This package comes with certain restrictions and obligations, most notably:

  • You cannot prevent the library from updating the databases.
  • You cannot use the GeoLite2 data:
    • for FCRA purposes,
    • to identify specific households or individuals.

This library's licensing is not suitable for commercial projects distribution.

If you plan on using node-geolite2 behind a firewall, you need to whitelist the IP range for the database updates.



This product includes GeoLite2 data created by MaxMind, available from

You can’t perform that action at this time.