# maxmind

> IP lookup using Maxmind databases

Latest version **5.0.7** (published 2026-08-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install maxmind
pnpm add maxmind
yarn add maxmind
bun add maxmind
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.0.7 |
| Published | 2026-08-01 |
| First published | 2013-03-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 2 |
| Unpacked size | 24 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 648 |
| Author | Dmitry Shirokov |
| Maintainers | runk |
| Keywords | maxmind, mmdb, geo, geoip, geoip2, geobase, geo lookup, ip base, geocode, timezone, asn, geo lookup, ip lookup |

## Links

- npm: https://www.npmjs.com/package/maxmind
- Repository: https://github.com/runk/node-maxmind
- Issues: http://github.com/runk/node-maxmind/issues
- npm.io page: https://npm.io/package/maxmind

## Dependencies (2)

- [mmdb-lib](https://npm.io/package/mmdb-lib.md) 3.0.3
- [tiny-lru](https://npm.io/package/tiny-lru.md) 13.0.0

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 5.0.7 (latest) — 2026-08-01
- 5.0.6 — 2026-04-01
- 5.0.5 — 2026-02-02
- 5.0.4 — 2026-02-01
- 5.0.3 — 2026-01-01
- 5.0.2 — 2026-01-01
- 5.0.1 — 2025-11-01
- 5.0.0 — 2025-08-06
- 4.3.29 — 2025-08-01
- 4.3.28 — 2025-07-01
- 4.3.27 — 2025-06-01
- 4.3.26 — 2025-06-01
- 4.3.25 — 2025-05-01
- 4.3.24 — 2025-01-22
- 4.3.23 — 2024-11-27
- … 91 more at https://npm.io/package/maxmind/versions

## README

# node-maxmind

Javascript module for Geo IP lookup using Maxmind binary databases (aka mmdb or geoip2).
Fastest Maxmind lookup library available - up to [17,000% faster](https://github.com/runk/node-maxmind-benchmark) than other libraries. Module has 100% test coverage with comprehensive test suite. It natively works with binary Maxmind database format and doesn't require any "CSV - {specific lib format}" conversions as some other modules do. Maxmind binary databases are highly optimized for size and performance so there's no point using other formats.

## GEO databases

You might want to use [geolite2](https://github.com/runk/node-geolite2) module with free geo databases. Alternatively, free databases available for [download here](http://dev.maxmind.com/geoip/geoip2/geolite2/). If you need better accuracy you should consider buying [commercial subscription](https://www.maxmind.com/en/geoip2-databases).

## Installation

```shell
npm i maxmind
```

## Usage

```typescript
import maxmind, { CityResponse } from 'maxmind';

const lookup = await maxmind.open<CityResponse>('/path/to/GeoLite2-City.mmdb');
console.log(lookup.get('66.6.44.4')); // inferred type maxmind.CityResponse

console.log(lookup.getWithPrefixLength('66.6.44.4')); // tuple with inferred type [maxmind.CityResponse|null, number]
```

### Sync API

You can use `Reader` class directly in case if you would want to instantiate it in non-async fashion. Use cases would include receiving a buffer database over network, or just reading it synchronously from disk.

```typescript
import { Reader } from 'maxmind';
const buffer = fs.readFileSync('./db.mmdb');
const lookup = new Reader<CityResponse>(buffer);
const city = lookup.get('8.8.8.8');

const [city2, prefixLength] = lookup.getWithPrefixLength('66.6.44.4');
```

Supported response types:

```
- CountryResponse
- CityResponse
- AnonymousIPResponse
- AsnResponse
- ConnectionTypeResponse
- DomainResponse
- IspResponse
```

## IPv6 Support

Module is fully compatible with IPv6. There are no differences in API between IPv4 and IPv6.

```javascript
const lookup = await maxmind.open('/path/to/GeoLite2.mmdb');
const location = lookup.get('2001:4860:0:1001::3004:ef68');
```

## Options

_maxmind.open(filepath, [options])_

- `filepath`: `<string>` Path to the binary mmdb database file.
- `options`: `<Object>`
  - `cache`: `<Object>` Cache options. Under the bonnet module uses [tiny-lru](https://github.com/avoidwork/tiny-lru) cache.
    - `max`: `<number>` Max cache items to keep in memory. _Default_: `10_000`.
  - `watchForUpdates`: `<boolean>` Supports reloading the reader when changes occur to the database that is loaded. _Default_: `false`.
  - `watchForUpdatesNonPersistent`: `<boolean>` Controls whether the watcher should be persistent or not. If it is persistent, a node process will be blocked in watching state if the watcher is the only thing still running in the program. _Default_: `false`.
  - `watchForUpdatesHook`: `<Function>` Hook function that is fired on database update. _Default_: `null`.

## Does it work in browser?

Current module is designed to work in node.js environment. Check out [mmdb-lib](https://github.com/runk/mmdb-lib) that's used under the bonnet - it's environment agnostic and does work in browser.

## IP addresses validation

Module supports validation for both IPv4 and IPv6:

```javascript
maxmind.validate('66.6.44.4'); // returns true
maxmind.validate('66.6.44.boom!'); // returns false

maxmind.validate('2001:4860:0:1001::3004:ef68'); // returns true
maxmind.validate('2001:4860:0:1001::3004:boom!'); // returns false
```

## GeoIP Legacy binary format

In case you want to use legacy GeoIP binary databases you should use [maxmind@0.6](https://github.com/runk/node-maxmind/releases/tag/v0.6.0).

## References

- [MMDB library](https://github.com/runk/mmdb-lib)
- MaxMind DB file format specification http://maxmind.github.io/MaxMind-DB/
- MaxMind test/sample DB files https://github.com/maxmind/MaxMind-DB
- GeoLite2 Free Downloadable Databases http://dev.maxmind.com/geoip/geoip2/geolite2/
- Great talk about V8 performance https://www.youtube.com/watch?v=UJPdhx5zTaw
- V8 Optimization killers https://github.com/petkaantonov/bluebird/wiki/Optimization-killers
- More V8 performance tips http://www.html5rocks.com/en/tutorials/speed/v8/

## License

MIT

---
_Source: https://npm.io/package/maxmind · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._