explaingit

hackl0us/geoip2-cn

★ 7,336GoAudience · ops devopsComplexity · 2/5Setup · easy

TLDR

A compact, auto-updated database of mainland Chinese IP addresses that is 40x smaller and more accurate than MaxMind's free alternative, used by Surge, Clash, and Shadowrocket to decide when to use a proxy.

Mindmap

mindmap
  root((GeoIP2-CN))
    What it does
      China IP database
      Proxy routing decisions
      Auto updates every 3 days
    Formats
      GeoIP2 MMDB file
      Plain IP-CIDR list
    Used by
      Surge and Clash
      Shadowrocket
      QuantumultX
    vs MaxMind
      40x smaller
      Better accuracy
      No registration needed
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Configure Clash or Surge to route mainland China traffic directly without a proxy using this more accurate database

USE CASE 2

Replace MaxMind's GeoLite2 in your proxy tool with a smaller China-only file that requires no registration to download

USE CASE 3

Set up firewall rules using the plain IP-CIDR list format to allow or block mainland Chinese IP ranges

Tech stack

GoGeoIP2MMDB

Getting it running

Difficulty · easy Time to first run · 5min

Contains only mainland China records, queries for other countries such as the US or Hong Kong will return no results.

In plain English

GeoIP2-CN is a compact database that records which IP addresses belong to mainland China. Tools like Surge, Clash, Shadowrocket, and QuantumultX use databases like this to decide whether a given internet connection should be routed directly or through a proxy. By knowing an IP belongs to China, those tools can send traffic there without a detour. The common alternative for this task is MaxMind's free GeoLite2 database, but the README explains several problems with that option: it requires registration to download, it is roughly 4 megabytes in size, and its accuracy for mainland China addresses is poor, sometimes misclassifying cloud provider IPs as belonging to Hong Kong or Singapore. Wrong classifications cause proxy tools to make bad routing decisions, resulting in slow or broken connections to certain sites. This project addresses those problems by combining two sources known for better China coverage, ipip.net and the Chunjun IP database, then merging and deduplicating the results into a file that contains only mainland Chinese address records. The result is roughly 100 kilobytes, a fraction of the MaxMind alternative, which means it loads faster and queries run more quickly. The database updates automatically every three days with no manual intervention and is hosted on GitHub with CDN distribution for fast downloads. Two formats are available: a plain IP-CIDR list for firewalls and older tools, and a GeoIP2 .mmdb file for newer proxy applications. Configuration guides for Surge, QuantumultX, Shadowrocket, and Clash are linked from the project wiki. One important limitation noted in the README is that this database contains only mainland China records. Rules that attempt to query for other countries such as the US, Australia, or Hong Kong will not work with it, since those entries are not present.

Copy-paste prompts

Prompt 1
Configure Clash to use the geoip2-cn MMDB file instead of MaxMind GeoLite2, show me the config file changes needed
Prompt 2
Set up Surge with geoip2-cn to route all mainland China IPs directly and send everything else through my proxy
Prompt 3
Download the geoip2-cn MMDB and use it in a Python script to check whether a given IP address is in mainland China
Prompt 4
Show me how geoip2-cn auto-updates every 3 days via GitHub Actions, can I fork this and host my own auto-updating mirror?
Open on GitHub → Explain another repo

← hackl0us on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.