# mmdb-lib

> Maxmind DB (MMDB) Library

Latest version **3.0.3** (published 2026-07-30) · MIT license · 680.9K weekly downloads

## Install

```sh
npm install mmdb-lib
pnpm add mmdb-lib
yarn add mmdb-lib
bun add mmdb-lib
```

## Health

**Score 85/100 (A)** — status: active.

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

Warnings: no esm support.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2026-07-30 |
| First published | 2020-07-11 |
| Weekly downloads | 680.9K |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 0 |
| Unpacked size | 33.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 48 |
| Author | Dmitry Shirokov |
| Maintainers | runk |
| Keywords | maxmind, mmdb, geo, geoip, geoip2 |

## Links

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

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads
- [@zappar/sharing](https://npm.io/package/@zappar/sharing.md) — 16 weekly downloads

## Recent versions

- 3.0.3 (latest) — 2026-07-30
- 3.0.2 — 2026-01-10
- 3.0.1 — 2025-06-17
- 3.0.0 — 2025-05-03
- 2.2.1 — 2025-05-02
- 2.2.0 — 2025-04-29
- 2.1.1 — 2024-05-29
- 2.1.0 — 2023-12-04
- 2.0.2 — 2022-02-03
- 2.0.1 — 2022-01-07
- 2.0.0 — 2022-01-07
- 1.4.0 — 2022-01-07
- 1.3.1 — 2021-12-20
- 1.3.0 — 2021-05-26
- 1.2.0 — 2020-10-06
- … 2 more at https://npm.io/package/mmdb-lib/versions

## README

# mmdb-lib

Javascript library for working with Maxmind binary databases (aka mmdb or geoip2).

Library is designed to be agnostic to environment and works equally well in node.js and browser. Module is fully compatible with IPv6. There are no differences in API between IPv4 and IPv6.

## Installation

```shell
npm i mmdb-lib
```

## Usage

```typescript
import fs from 'fs';
import * as mmdb from 'mmdb-lib';

// Get a buffer with mmdb database, from file system or whereever.
const db = fs.readFileSync('/path/to/GeoLite2-City.mmdb');

const reader = new mmdb.Reader<CityResponse>(db);
console.log(reader.get('66.6.44.4')); // inferred type `CityResponse`
console.log(reader.getWithPrefixLength('66.6.44.4')); // tuple with inferred type `[CityResponse|null, number]`
```

Supported response types:

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

## Usage in browser-like environments

Library expects to receive an instance of `Buffer` during instantiation of `Reader`. Since there is no direct alternative of node's `Buffer` in browser, you can use https://github.com/feross/buffer that mimics native `Buffer` interface. Neither `ArrayBuffer` nor `Uint8Array` is supported right now. Another requirement is [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) object available.

## Options

_Reader(db:Buffer, [options])_

- `options`: `<Object>`
  - `cache`: `<Object>` Cache helper. [tiny-lru](https://github.com/avoidwork/tiny-lru) is great basic option. Only two methods expected: `get(key: string | number): any` and `set(key: string | number, val: any): void`.

## References

- Loosely based on https://github.com/PaddeK/node-maxmind-db
- 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

## Contributing

All contributions are welcome. Please make sure to add tests for your changes.

You need to initialise the repository with the following command:

```shell
git submodule update --init --recursive
```

Then you can run tests with:

```shell
npm test
```

For a quick lookup benchmark against the bundled test database, run:

```shell
npm run benchmark
```

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