# qqwry.ipdb: the classic Chinese IP database in IPDB format

> qqwry.ipdb republishes the free CZ88 IP address database in the IPDB format used by IPIP.net, in two variants, one matching the original layout and one with country, province, city, district and carrier fields.

**metowolf/qqwry.ipdb** — 🐈️ 纯真数据库 IPIP.net 格式版，Make qqwry.ipdb Great Again!!!

- Repository: https://github.com/metowolf/qqwry.ipdb
- Stars: 611 · Forks: 87
- Language: JavaScript
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/metowolf-qqwry-ipdb

## The same data, in a format the parsers already accept

This repository republishes the well known free Chinese IP address database, the one distributed by CZ88, in the IPDB format that IPIP.net defines. The project description calls it the IPIP.net format edition of the qqwry database, simplified and normalised down to country, province, city and carrier, with IPv4 and IPv6 support. That normalisation is the substance of the work. The original file is a legacy format with its own quirks, and the tooling built around it, the ipdb library and the ipdb-packer project, all speak IPDB. Repackaging the data means the existing parsing code works without changes, which is the whole point of the project. The version of the data follows the upstream update site update.cz88.net, and the project notes that on 2024.12.28 the reverse engineering of the CZDB format was completed, at which point the project resumed updating.

## Two packages, and the difference is which fields are filled in

There are two npm packages here and choosing between them is a single decision about field content. The original package, qqwry.raw.ipdb, keeps the shape of the qqwry format. It is compatible with all of the official IPDB format parsing code and provides the two fields that correspond to the original ones, country_name and region_name, while the remaining three, city_name, owner_domain and isp_domain, are present but empty and exist only as placeholders for compatibility. The standard package, qqwry.ipdb, fills the fields in the way the daily professional IPIP.net product does, with country_name, region_name as the province for addresses in China, city_name at city level, district_name for the district, owner_domain, isp_domain for the carrier, plus country_code in ISO3166-1 form and a continent_code. If your code already reads those five fields and the two extra ones come back empty, you are on the original package and should switch.

## The data file is served from npm CDNs

Neither package carries the database inside it, which is the point. The files are published on npm and served from the usual content delivery networks, with jsdelivr and unpkg each listed as the source of the qqwry.ipdb file for the original package and for the standard one. The distinction matters for deployment. A browser application can fetch the file from a CDN without a server of its own, and the same URL works for both packages, so switching from the raw variant to the standard one is a URL change rather than a build change. The file itself is large, so a deployment that fetches it on every request would be wasteful, and a sensible setup downloads it once at build time or caches it locally. The repository also carries a build.sh script and a src directory, which is where the conversion from the upstream format to IPDB happens, along with the packer dependency that writes the result.

## Reading an address with the ipdb library

The example in the project documentation uses the metowolf/ipdb parsing library, and the install is a pair of packages, the library and the database:

```sh
$ yarn add ipdb
$ yarn add qqwry.ipdb
```

The code then constructs a parser with the database and asks it to find an address:

```javascript
const IPDB = require('ipdb');
const qqwry_ipdb = require('qqwry.ipdb');
const ipdb = new IPDB(qqwry_ipdb);

ipdb.find('183.62.57.1');
```

The result object carries a data block and a code, and the data block holds the parsed fields along with the address that was looked up and a bitmask describing the size of the network the entry covers. The code being zero is the signal that the lookup succeeded, and the bitmask tells you that the entry describes a whole /24 rather than a single address, which matters when you aggregate or cache results. The dependency list in the package metadata is what produces that structure, with the ipdb library doing the format handling and the database package supplying the bytes.

## The data pipeline depends on three small packages

The runtime dependencies in the package metadata describe the pipeline. @ipdb/czdb handles the CZDB side of the conversion, fast-cidr-tools deals with CIDR arithmetic, which is what makes IPv4 and IPv6 coverage work in one database, and @msgpack/msgpack at 3.0.0-beta2 provides the serialisation the IPDB format is built on. The development dependencies are the tools that produce the file rather than read it, @ipdb/packer for writing the IPDB database and ipdb for reading it back during the build, and both sit in devDependencies rather than dependencies, so they are not installed by a consumer. The project also records its provenance in the acknowledgements, crediting the ipdb library for the IPDB parsing solution, the ipdb-packer project for the packaging solution, an article on the analysis of the IPIP.net address database format for the reverse engineering, the qqwry-mirror project for inspiration, and CZ88 for the free offline database itself. That is worth reading if you need to know how a data file is licensed, since the code licence and the data licence are separate questions.

## A package version that is really a data version

Two details in the package metadata affect how you depend on this. The version field reads 2024.12.28, which is a date rather than a semantic version, and that matches the note in the documentation that the CZDB reverse engineering finished on that date and updates resumed. A date-shaped version is a reasonable convention for a package whose content is a database snapshot, and it makes it obvious which vintage of the upstream data you have installed, but it also means the usual tooling assumptions about version ranges do not apply, since 2024.12.28 sorts as a string rather than as a release. The second detail is the licence. The package metadata declares MIT, while the repository itself is recorded as having no classifiable licence, so the terms in package.json are the ones that apply to the code you install. The upstream database carries its own terms from CZ88, and the project explicitly thanks them for the free offline database, so anyone redistributing the data file rather than consuming it should check that separately.

## Conclusion

Adopt qqwry.ipdb if you need a freely hosted IP address database in a format the IPIP.net parsers already understand, and pick the standard package when you need city, district and carrier fields. Do not use it as a substitute for a paid IPIP.net plan if you need accuracy guarantees, and note the npm version string doubles as the data version, so pinning the package pins the database snapshot.

## FAQ

### What is the difference between qqwry.raw.ipdb and qqwry.ipdb?

The original package keeps the qqwry layout, filling only country_name and region_name and leaving city_name, owner_domain and isp_domain as empty placeholders. The standard package provides the full set including city, district, owner domain, carrier, ISO3166-1 country code and continent code.

### How do I look up an IP address with qqwry.ipdb?

Install the ipdb library and the qqwry.ipdb package, then create a parser with new IPDB(qqwry_ipdb) and call find with the address. The result carries the parsed fields, the address itself and a bitmask describing the network size of the entry.

### Where is the qqwry.ipdb database file served from?

From npm content delivery networks. Both packages list a jsdelivr and an unpkg URL pointing at the qqwry.ipdb file, so the same CDN URLs work whether you use the original or the standard package.

### Does qqwry.ipdb support IPv6?

Yes. The project states that IPv4 and IPv6 are supported, and the fast-cidr-tools dependency in the package metadata handles the CIDR arithmetic for both address families.

### How often is the qqwry.ipdb database updated?

The version follows the upstream update site update.cz88.net, and the package version is a date, 2024.12.28, matching the day the CZDB format reverse engineering finished and the project resumed updating. The last push was on 2026-09-25.

## Sources

- [Issues](https://github.com/metowolf/qqwry.ipdb/issues)
- [metowolf/qqwry.ipdb on GitHub](https://github.com/metowolf/qqwry.ipdb)
- [README](https://github.com/metowolf/qqwry.ipdb/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/metowolf-qqwry-ipdb