ip2region: offline IPv4 and IPv6 lookups from a single xdb file

What ip2region solves, and for whom

Resolving an IP address to a country, province, city and ISP normally means calling a remote API or loading a vendor database. ip2region takes the first option off the table. It is an offline library: the README describes it as an offline IP address localization library and IP localization data management framework, supporting both IPv4 and IPv6, with query efficiency at the 10-microsecond level. The unit of distribution is a file, the xdb file, plus a client that reads it.

The audience is narrower than the topic list suggests. If you run a service that must annotate request logs, block or route traffic by region, or enrich events without an outbound call, this is aimed at you. It also fits teams that already have their own IP ranges and want a storage format rather than a vendor relationship: the README states that region information supports full customization, and that you can append data such as GPS information, international standard regional codes or zip codes to the region string. That second use, using ip2region to manage your own IP localization data, is the part people overlook.

The xdb format and the three query modes

The data flow has two halves that meet at one file. On the generation side, a maker program reads raw segment rows and writes an xdb file; the README says the generation program checks and completes the merging of adjacent IP segments and performs deduplication and compression of identical regional information. On the query side, a searcher client opens that file and answers lookups. The field format is fixed for the built-in data: Country|Province|City|ISP|iso-alpha2-code. Localization information for China is entirely in Chinese; regional information for non-China areas is entirely in English.

Query performance is a function of how much of the file you keep in memory, and the README names three levels. Reading from the xdb file on disk gives single-query response at the 10-microsecond level. Enabling vIndex index caching uses a fixed 512KiB of memory to cache vector index data, removing one disk IO operation and keeping average query efficiency within 100 microseconds. Caching the entire xdb file removes disk IO entirely and holds 10-microsecond level efficiency, at a memory cost equal to the xdb file size.

That is the real design decision in this project, and it is a capacity question rather than a performance one. vIndex is the middle option: 512KiB is a fixed, predictable number you can budget, whereas whole-file caching scales with the data you generated. The README does not publish the size of the bundled data/ip2region_v4.xdb and data/ip2region_v6.xdb files, so the memory cost of full caching is something you measure against your own build, not something the documentation tells you.

Installing a searcher and running a first lookup

There is no single install command for the project. Each language binding lives under binding/<language>/ and carries its own README with API introductions, usage documentation and test programs. The top-level README points you there rather than giving one global procedure, so the first step is choosing the client for your stack. Supported bindings with both IPv4 and IPv6 are Golang, PHP, Java, C (std=c99), Lua_c, Lua, Rust, Python, Javascript, Csharp, Erlang, Nginx, C++ and Cangjie. Community-maintained clients exist for PHP via composer, Node.js via an addon, Ruby and a data conversion tool, and those live in third-party repositories.

The Go entry point is the one to read first, since the repository's primary language is Go. The exact API names are in binding/golang/README.md, which the top-level README directs you to; the shape of the work is to open the xdb file, construct the searcher, and call the lookup with an address string. A lookup returns the region string in the fixed field order described above, so a Chinese address comes back with Chinese region fields and a non-Chinese address comes back with English ones.

For a first real use, pick the query mode deliberately. Whole-file caching gives the fastest answer but holds the file in memory for the life of the process. vIndex caching costs a fixed 512KiB and is the safer default for a long-running service that handles many addresses. Plain file queries avoid the memory commitment altogether.

If you need to build your own data rather than use the bundled files, the maker programs are listed separately: Golang, Java, Rust and C++ support both IPv4 and IPv6, while the Python and Csharp makers are marked IPv4 only. That asymmetry matters if your pipeline is written in Python and you need IPv6 segments generated.

Where ip2region is the wrong tool

Accuracy is the first boundary. The README is direct about it: the raw data ./data/ipv4_source.txt and ./data/ipv6_source.txt included in the project are updated irregularly, and for scenarios with high requirements for data accuracy and update frequency it recommends purchasing commercial offline data from the Ip2Region Community or third-party vendors. If your product depends on current allocation data, the bundled files are a starting point, not a feed. The project frames its core as researching the design and implementation of IP data storage and fast querying, which is an honest description of where the effort goes.

The second boundary is the fixed field shape. Country|Province|City|ISP|iso-alpha2-code is what the built-in data gives you. Appending GPS coordinates or postal codes is supported, but that means generating your own xdb from your own source rows, not querying the bundled file and hoping for extra columns.

The third is the update path. The README lists manual editing of the source files using the editing tools provided by ip2region, with data sources being the ip2region community, project issues tagged [Data_Updates], and other custom data. There is no documented incremental sync or rollback procedure for a deployed xdb file; replacing it means shipping a new file and restarting or reloading the searcher. If you need hot data updates with versioning, that is outside what the README describes.

ip2region against a hosted geo-IP API

The obvious alternative is a hosted lookup service. The difference is architectural, not just operational. A hosted API resolves the address on someone else's infrastructure, so the data is as fresh as the vendor makes it and you pay per query or per seat; ip2region resolves it in your process, so latency is a memory or disk access and there is no per-query cost, but the data is as fresh as the last xdb file you generated.

That trade is worth stating plainly. A hosted API lets you skip the question of where the data comes from. ip2region forces the question, and the README answers it by pointing at commercial offline data for anyone who needs accuracy, which means the project is often a storage and query layer in front of data you buy elsewhere. Teams that want the offline property but not the data responsibility will find themselves maintaining a generation pipeline anyway.

The other axis is language coverage. Hosted services give you HTTP, which every language speaks. ip2region gives you native clients in more than a dozen languages, listed in the README's binding table, plus community clients for PHP composer, Node.js, Ruby and a conversion tool. That is unusually broad for a library like this, and it is the strongest argument for choosing it over writing your own reader for a vendor's binary format.

Maintenance, licensing and what a version bump costs

The repository is not archived, and the last push was on 2026-09-08, the same day v3.18.0 was released. Before that, v3.17.0 landed on 2026-07-10 and v3.16.0 on 2026-05-07. Releases arrive on a rough two-month cadence, and the version numbers are shared across the bindings and makers rather than per language, which means a bump can touch any client.

The practical upgrade cost depends on which half you use. If you only consume a searcher, an upgrade is a dependency change plus, potentially, a new xdb file. If you run a maker, an upgrade can change the generation output, and since the xdb format is described as version-compatible for queries, the risk sits in regenerating and redistributing data rather than in the reader. The README does not document a migration procedure between xdb versions, so treat a maker upgrade as something to test against a copy of your source data before you replace a production file.

On licensing: the repository metadata reports the licence as NOASSERTION, which means GitHub could not map the LICENSE.md file to a recognized identifier. The LICENSE.md file is present at the top level, so the terms exist, but you should read it yourself before shipping the data files or the bindings inside a product. The README also points to commercial offline data sold through ip2region.net, which is a separate commercial arrangement from the repository licence; do not assume the repository terms cover purchased data or the reverse. This is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt ip2region when you need IP-to-region answers inside your own process, with no network call and no per-query fee, and when the built-in Country|Province|City|ISP|iso-alpha2-code shape fits your records. Do not adopt it as a substitute for a commercial feed if your accuracy requirement is high, because the README states the bundled ipv4_source.txt and ipv6_source.txt are updated irregularly and points buyers to commercial offline data. Before committing, check the searcher README for your language to confirm both IPv4 and IPv6 are listed, and decide which of the three query modes you need, since whole-file caching costs memory equal to the xdb file size.

Frequently asked questions

Official sources

1. Issues
2. lionsoul2014/ip2region on GitHub
3. Project website
4. README
5. Releases