Loyalsoldier/geoip: a weekly rebuild of the same IP country data into nine formats

One dataset, published as nine file formats every Thursday

The project takes one input, MaxMind's GeoLite2 Country CSV data, and turns it into a set of files that nine different pieces of software can each read without conversion. The list in the README covers the V2Ray dat format used by V2Ray and Xray-core, the MaxMind mmdb format, sing-box SRS, mihomo MRS, Clash rulesets, Surge rulesets, and Nginx allow and deny lists. The repository description adds Shadowrocket, Quantumult X, hysteria, Trojan-Go and dae to the set of consumers.

The schedule is fixed rather than event-driven. The README states that files are generated automatically every Thursday, and the release history bears that out. Two of the three most recent releases fall on a Thursday: 202609100029 was published on 2026-09-10 and 202609170030 on 2026-09-17. The third, 202609040655, was published on 2026-09-04, a Friday, and its tag carries a morning hour where the other two carry just after midnight. That pattern looks like a run that slipped off the weekly slot rather than a deliberate change, and it is the sort of detail a scheduled job in a repository's own CI will explain better than any changelog will.

The tag names themselves encode a timestamp, twelve digits with no separator: the date followed by the hour and minute. So 202609170030 is 2026-09-17 at 00:30. There is no semantic version anywhere in this repository's releases, which is unusual and worth internalising before you write any automation against it.

The China override is the only real editorial decision

Everything about this project follows from MaxMind's data except one thing, and that one thing is the reason to read the README closely rather than skim the feature list.

By default the project builds each country and region file from the MaxMind GeoLite2 Country CSV data linked in the README. For Mainland China it does not. Both the IPv4 and the IPv6 ranges for China are taken instead from the china-operator-ip list published by gaoyifan, and the README lists those two files as explicit replacements. The distinction matters for anyone routing traffic inside China, where the useful question is not which country an address is registered in but which network operator holds the allocation. Country-level geolocation cannot answer that; an operator list can, and it can be used to send domestic traffic out the local interface instead of into a proxy.

On top of that substitution the project adds categories that have nothing to do with geography at all: cloudflare, cloudfront, facebook, fastly, google, netflix, telegram, twitter and tor. Each is available as both a geoip tag and, where the format allows, an uppercase country code. Tor is the interesting one, because it turns the data file into something closer to a blocklist, and that is a different use from the one the project name suggests. The README is explicit that the added categories exist for users with special requirements.

The category list also includes geoip:private, which is not a country at all but the set of internal and reserved addresses. Every one of these can be written as a two-letter code, and the README points at the Iban country code list for the rest.

Pointing V2Ray at the data without downloading it by hand

The client configuration is where most of the practical value sits, and the README keeps it in collapsible sections per client. V2Ray and Xray-core read the dat file if you place it in the program directory, and the routing rules then reference categories by tag. The first rule sends Mainland China and private ranges directly, the second proxies a set of overseas and service categories:

"routing": {
  "rules": [
    {
      "type": "field",
      "outboundTag": "Direct",
      "ip": [
        "geoip:cn",
        "geoip:private",
        "ext:cn.dat:cn",
        "ext:private.dat:private",
        "ext:geoip-only-cn-private.dat:cn",
        "ext:geoip-only-cn-private.dat:private"
      ]
    },
    {
      "type": "field",
      "outboundTag": "Proxy",
      "ip": [
        "geoip:us",
        "geoip:jp",
        "geoip:facebook",
        "geoip:telegram",
        "ext:geoip-asn.dat:facebook",
        "ext:geoip-asn.dat:telegram"
      ]
    }
  ]
}

Note the ext prefixes. Those are for the smaller split files, cn.dat, private.dat and the slim geoip-only-cn-private.dat, so you can load only the categories a rule needs instead of the whole database.

mihomo can fetch the file itself, which is the shortest configuration in the README:

geodata-mode: true
geox-url:
  geoip: "https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/geoip.dat"

hysteria uses a one-line-per-category syntax instead, and Trojan-Go has a router object with bypass, proxy and block lists. Both expect the dat file already sitting in the program directory, which means the update path for those two is whatever your package manager does, not the CDN. The README also notes that the dat format cannot be used for Nginx, which is the clearest sign in the repository that these formats are not interchangeable.

The Go module is a converter, and its dependency list explains why

The source is small enough to read in one sitting. Six Go files sit at the repository root: main.go and init.go for the command entry point and configuration, convert.go for the format conversions, merge.go for combining source files, list.go for enumerating what is available, and lookup.go for answering a single address query. Alongside them are a config.json, a configuration.md, a lib directory, a plugin directory, and both LICENSE and LICENSE-GPL.

The dependencies in go.mod are the interesting part, because they map one to one onto the output formats. mmdbwriter and maxminddb-golang v2 handle writing the MaxMind format, geoip2-golang v2 provides the reader API, and sing-box v1.14.0 is a direct dependency, which is how the SRS output is produced rather than by reimplementing sing-box's rule compiler. cobra provides the command line interface, gjson and hujson handle JSON with comments, netipx manages address ranges, klauspost/compress and protobuf do the compression and serialisation, and yaml.v2 covers the Clash and Surge rulesets.

The module targets Go 1.26. That is a recent floor for a repository with six source files, and it means building from source requires a toolchain most stable distributions do not ship by default. In practice you consume this project as files rather than as a binary, which is why the CLI matters mostly to people who want different sources or different category definitions.

Every artifact is checksummed, and the mirror question never goes away

Each published file ships with a .sha256sum companion, and the README flags that plainly. It is a small detail and the right one: these files are fetched over a content delivery network and dropped into a directory that decides where your traffic goes, so an unverified download is a routing decision made by whoever answered a DNS query.

The README also offers two hosts for every file, raw.githubusercontent.com and cdn.jsdelivr.net, and tells you to fall back to fastly.jsdelivr.net if the second is unreachable. That fallback chain is a direct response to a real operational fact: in some networks these hosts are individually reachable and collectively unreliable, and the same week that one is down is the week a client silently loses its routing table.

There is one more piece of the setup that no format list will tell you. The files are committed to a branch named release rather than attached to a release as assets, so the download URLs point at a branch that changes under you. That is what makes the CDN URLs above work, and it is also why pinning to a tag or verifying the checksum against a specific build matters more here than it would in a project that publishes immutable assets.

What the metadata says and what the repository actually contains

Two details in this repository will trip up anything that trusts API metadata.

The first is the license. The repository reports its license as CC-BY-SA-4.0, a Creative Commons terms aimed at data and documentation rather than source code. The repository root contains both a LICENSE file and a LICENSE-GPL file. A project that ships a converter written in Go and redistributes someone else's country database has two genuinely different things to license, and the single reported value only covers one of them. If you are considering redistribution, read both files rather than trusting the field.

The second is that the repository has no homepage set. For a project with this many consumers there is no documentation site, no changelog and no issue template to speak of, and six open issues is a low number for a repository this widely consumed. What documentation exists is the README itself, which is bilingual, with Chinese and English paragraphs for most sections, and which is the only place the format list, the category list and the client configurations are written down.

The repository is not archived, its default branch is master, and the last push was on 2026-09-17. The activity here is automated and scheduled, so an empty commit history tells you less than it would in most projects.

Editorial conclusion

What makes this repository useful is not the data, which anyone can obtain, but the repackaging: one weekly job, one set of corrections, and nine file formats so that a routing rule can be written without first converting an mmdb into whatever your client happens to read. Read it as infrastructure with a weekly expiry date. Every artifact you adopt is a snapshot of the network on a Thursday, and the tag naming tells you which Thursday without opening the file. Point a client at geoip-only-cn-private.dat if you want the small case, run the CLI when the published files do not match your sources, and remember that the client-specific configuration blocks in the README, not the data files, are where the compatibility surprises live.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. Loyalsoldier/geoip on GitHub
4. README
5. Releases