v2fly/geoip turns country IP data into V2Ray routing files

Routing rules need country IP data, and this publishes it monthly

The problem is narrow and concrete. V2Ray, called Project V in the README, routes traffic according to rules that can match on the country an IP address belongs to, and matching on country means having a database of IP ranges per country somewhere on disk. Nobody wants to maintain that by hand.

This project closes that gap. The README states that it releases GeoIP files monthly for routing purposes in Project V, and it also provides a command-line interface tool for users to customize their own GeoIP files. Those two halves matter: the published files remove the work entirely for most users, and the CLI exists for the people whose requirements the monthly files do not meet.

The published set is not a single file. The download list names geoip.dat, geoip-only-cn-private.dat, cn.dat and private.dat, and each one is offered from two places, a GitHub releases download URL and a jsDelivr CDN path pointing at the release branch. Every file is offered alongside a matching .sha256sum, which is the detail to notice: the project expects you to verify what you downloaded.

The release naming reflects the schedule. The three most recent release tags are timestamps, 202610050438, 202609050329 and 202609040609, and the last push to the repository was on 2026-10-19. The repository is not archived.

The CLI is a pipeline with two named ends

The customisation tool is described in terms of two concepts, input and output, and that framing is the whole design.

The README puts it precisely. The input is the data source and its input format, whereas the output is the destination of the converted data and its output format. What the CLI does is aggregate all input format data, then convert it to output format and write it to GeoIP files by using the options in the config file.

So this is not a converter that maps one format to another. It is a fan-in and fan-out pipeline. Several sources of different kinds are combined, and the combined result is written out in one or more target formats. That is why a config file is central rather than optional, because the pipeline shape, the sources, and the outputs are all configuration.

The repository layout supports the modular reading. There is a plugin/ directory alongside main.go, init.go, lib/, config.json and configuration.md, and the format names in the documentation, maxmindGeoLite2CountryCSV, dbipCountryMMDB, v2rayGeoIPDat, are identifiers rather than file formats you would guess from a directory listing. The list of available formats is a runtime question rather than a compile-time constant, which is why the tool ships a command that prints them.

Seven input formats and only two outputs

The supported input formats are the part of the tool that determines what you can build.

There are seven. cutter removes data from previous steps. maxmindGeoLite2CountryCSV converts MaxMind GeoLite2 country CSV data to other formats. maxmindMMDB converts a MaxMind country mmdb database. dbipCountryMMDB converts the DB-IP lite country mmdb database. private converts LAN and private network CIDR. text converts plain text IP and CIDR entries. v2rayGeoIPDat converts an existing V2Ray GeoIP dat file.

Two of those deserve comment. The cutter format is a filter that applies to data produced by earlier steps, which is how you exclude regions or ranges from an otherwise complete source. The private format is what produces the private.dat output, covering LAN and private network ranges that belong in a routing table but in no country database.

The output side is much narrower, with two formats: text, which writes plain CIDR lines, and v2rayGeoIPDat, which writes the binary format V2Ray loads. The asymmetry is deliberate and it is the key thing to understand about the tool. Inputs are numerous because the sources of country data are numerous and messy. Outputs are few because there are only two things worth doing with the result, loading it into V2Ray or reading it.

The same asymmetry explains a practical consequence. If you want to merge several databases, or drop a range from a MaxMind file, or convert your own list, the tool does all of that. If you want an output format it does not have, such as something other than CIDR text or the V2Ray dat format, the tool will not produce it.

Building the files yourself, step by step

The customisation procedure is a short, explicit sequence, and it assumes you already have the source data.

The documented steps are to install golang and git, clone the project code, navigate to the project root, install the project dependencies, edit the config file, and then generate the files:

git clone https://github.com/v2fly/geoip.git
cd geoip
go mod download
go run ./

The configuration file is config.json in the project root, and the README points to configuration.md for the available options. The generated files land in an output directory by default, and you can point the tool at a different config with the -c flag, or ask for usage information with -h.

If you would rather have a binary, the README documents a direct install path:

go install -v github.com/v2fly/geoip@latest

The help output of the built binary is short, which tells you how little surface there is:

$ ./geoip -h
Usage of ./geoip:
  -c string
    	Path to the config file (default "config.json")
  -l	List all available input and output formats

Two things are worth noticing before you start. First, the module targets a recent Go, with go.mod declaring go 1.26, so the toolchain you have locally needs to be new enough. Second, and more important, the tool does not fetch the upstream databases for you. The input formats describe sources you supply, so the MaxMind GeoLite2 CSV or the MaxMind or DB-IP mmdb files have to be on your disk before the pipeline can consume them. The go.mod dependency list shows the mmdb side is handled by the geoip2-golang and maxminddb-golang modules, so the parsing of those databases is already done for you.

How V2Ray routing consumes these files

The reason the dat format matters is visible in the routing configuration the README shows.

A V2Ray routing rule lists IP matches, and the list mixes two styles. The geoip: form refers to a country code inside a standard geoip database:

"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"

The ext: form names a file and a code inside it, and the file part is the point. A rule pointing at ext:cn.dat:cn is reading a specific dat file that you placed in the V2Ray configuration directory, not the built-in database. The same file can be referenced for several codes at once, which is how the example uses geoip-only-cn-private.dat for both cn and private.

That is the mechanism that makes the whole project work with V2Ray. The monthly releases give you the files, the ext: syntax tells V2Ray to load your copy rather than the default one, and the rules decide which traffic is Direct and which goes to a proxy.

The example configuration also shows how the different files divide the work. Private and local ranges are matched alongside country codes in the Direct rule, and individual addresses such as 223.5.5.5/32 sit next to the geoip and ext entries, so country matching is one match source among several rather than the whole policy. When you build your own files, the naming convention carries meaning: a file called cn.dat and one called geoip-only-cn-private.dat differ in whether private ranges are included, and the rule has to match the file you actually generated.

Checksums, monthly cadence and where the data ages

Two properties of this project deserve more attention than they usually get.

The first is verification. Every downloadable file is published with a matching .sha256sum, and the URL patterns make checking straightforward, since the checksum file sits at the same path as the data file on both the GitHub releases side and the jsDelivr side. For a file that decides where your traffic is sent, an unattested download from a CDN is exactly the wrong thing, and the project gives you the means to check it.

The second is cadence, and it is where the limitations live. The releases are monthly. The repository produces GeoIP files monthly for routing purposes in Project V, and the release tags are timestamps rather than version numbers, which tells you the artifacts are dated records rather than a maintained format.

That has a direct consequence. The database reflects the source data as of the release date, and the mapping of an IP range to a country changes over time as address assignments move. A rule that matched correctly last month can match differently this month without anything in your configuration changing, and the symptom is a misrouted request rather than an error. If your routing depends on country matching for anything that matters, the date of the dat file you loaded is part of your configuration state and belongs in the same place as the configuration itself.

The upstream data has its own refresh cycle, which this project cannot control. It converts what it is given at build time, so a stale source file produces a stale output with a fresh timestamp, which is precisely the failure mode that checking the release date is meant to catch.

Licence and the maintenance question

The licence is CC-BY-SA-4.0, which covers the generated data files and the code in the repository. The share-alike requirement matters here in a specific way. If you take the published GeoIP files and modify them, for instance by applying the cutter step to remove ranges, the resulting dataset carries an obligation to be shared under the same terms. For personal use that is invisible. For a commercial product that bundles a modified geoip.dat, it is a decision to make before you ship.

Read the licence text for yourself rather than taking a summary as guidance, since the details of what counts as adaptation in a data file are not something to guess at.

On maintenance, the picture is good. The last push was on 2026-10-19, the repository is not archived, the primary language is Go, and the module has been updated to declare go 1.26 with current versions of its dependencies, including geoip2-golang and maxminddb-golang. The releases continue to arrive on the monthly schedule the project advertises.

The upgrade cost is correspondingly low. The tool is installed with go install, the configuration is a single JSON file, and running the pipeline regenerates the outputs into an output directory. There is no daemon to restart and no long-lived state. What does carry over between versions is the config file, since configuration.md is the reference for its options, and the data files your V2Ray configuration references by name.

Editorial conclusion

v2fly/geoip suits anyone running V2Ray whose routing rules depend on country based IP data and who wants either a monthly download or a build pipeline they control. It does not suit a general geolocation application, because the output formats are limited to plain CIDR text and the V2Ray dat format, and it is the wrong tool if you need per city or per ASN resolution. Before you rely on it, check the release date of the dat file your rules actually load, since a stale country database silently misroutes traffic, and read configuration.md to see which input formats you would need to supply yourself if you build the files yourself.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. Project website
3. README
4. Releases
5. v2fly/geoip on GitHub