GeoIP and GeoSite Databases: Manual Updates, Auto-Updates, and Rule Syntax

First, know the difference: IP geolocation, domain categories, and subscriptions

A successful node subscription update does not mean your routing databases are up to date. Subscriptions typically provide nodes, proxy groups, and rules; GeoIP and GeoSite are local data files read by the core. If a domain suddenly hits the fallback rule, check the rule order, whether the category exists, and whether the database loaded. Repeatedly clicking the subscription update button won't help.

This guide focuses on the mihomo core. The original Clash, some older Premium versions, and current mihomo releases support different fields, so don't assume the configuration below works with every program called Clash. Check the core information in your client or its startup logs to identify the core in use. From the command line, run mihomo -v to check the version.

Check the data source and the core's working directory

Choose a source that includes the categories you need

mihomo commonly uses data from MetaCubeX's meta-rules-dat project. Domain categories are also available from domain-list-community and derivative builds, while several projects publish GeoIP datasets. Don't just pick the file that downloads fastest. Check its format, included categories, and the maintainer's release notes.

• If your rule says GEOSITE,cn,DIRECT, the domain database must include the cn category.
• A rule referencing a service name doesn't mean every source includes a category with that name. Test your configuration again whenever you switch databases.
• Don't save a plain-text domain list, ruleset YAML file, or failed download's HTML error page as GeoSite.dat.
• Using a consistent source can reduce category mismatches, but check the release notes anyway; data updates can change which rules match.

Find the core's data directory—don't guess the install location

A GUI client's program directory, configuration directory, and core data directory may all be different. On Windows, the core may run as a service and read files from the service's working directory, not the directory used when you launch the program as your own user. Check startup logs for the configuration, database, or download paths. If the client offers an “Open config directory” option, verify that the core actually reads its data files from there.

For a command-line setup, use -d to specify the working directory. This command sets the data directory to the current user's .config/mihomo and reads the configuration from there. Create the directory first and make sure it contains a valid config.yaml.

mihomo -d "$HOME/.config/mihomo" \
  -f "$HOME/.config/mihomo/config.yaml"

This example is for Unix-like shells; it isn't the default path for every client. Linux filenames are case-sensitive: a release asset may be named geosite.dat, but save it as GeoSite.dat if that's what the core expects. The same applies to Country.mmdb. Replacing a file in the wrong directory a hundred times only updates a file the core never reads.

Manual replacement: back up, test, then restart

Manual updates make sense for offline devices, failed automatic downloads, pinned data versions, or a switch to a different database source. Don't overwrite a file while the client is downloading a database. Exit the client or stop the relevant service first, then confirm the core process has stopped.

1. Check the current mode. Look at geodata-mode in the effective configuration. When set to false, GeoIP uses MMDB; when set to true, it uses DAT. GeoSite always uses a separate domain database.
2. Keep a rollback copy. Back up the file you're replacing and note its source and download date. Don't delete your only working copy.
3. Download to a temporary file. Confirm the HTTP request succeeded before moving the file into the core's working directory. Never let a partial download take the place of the live file.
4. Test the full configuration. Use the same core, configuration file, and data directory as the production setup.
5. Restart the core. Refreshing the UI or reopening the connection page may not reload the databases. Then check the startup logs and verify which rule actually matches.

Here's an example of updating GeoSite.dat with Bash. It assumes you've confirmed the data directory and stopped the core. Handle other databases according to the active mode; changing the file extension alone isn't enough.

cd "$HOME/.config/mihomo" || exit 1

if [ -f GeoSite.dat ]; then
  cp -p GeoSite.dat GeoSite.dat.bak || exit 1
fi

curl --fail --location --retry 2 \
  --output GeoSite.dat.new \
  "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat" \
  && mv GeoSite.dat.new GeoSite.dat

mihomo -t -d "$PWD" -f "$PWD/config.yaml"

curl --fail returns an error for common HTTP failures, but it can't guarantee the downloaded file is valid. The core must verify its format and categories. If the test fails, keep the error output and restore your backup. If the old file is available, run cp -p GeoSite.dat.bak GeoSite.dat, then test again. Start the service only after the test passes.

Automatic updates: geox-url and update intervals

In mihomo versions that support these fields, geox-url sets the download sources, geo-auto-update enables scheduled updates, and geo-update-interval is measured in hours. Setting a download URL alone does not enable periodic updates. The snippet below shows top-level fields to merge into your existing configuration; it isn't a complete config with proxies and proxy groups.

# Top-level fields, at the same level as dns and rules
geodata-mode: true
geo-auto-update: true
geo-update-interval: 24

geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country.mmdb"

• geoip points to geoip.dat. This example enables DAT mode, which GeoIP rules use.
• geosite points to GeoSite.dat, which provides the domain categories used by GEOSITE rules.
• mmdb points to Country.mmdb, used when switching back to MMDB mode. Listing a source doesn't mean every file needs to be downloaded every time.
• 24 means 24 hours—not midnight every day or 24 minutes. Don't expect updates to run like a continuously available service while the device is asleep or the core is stopped.

A missing database file may trigger a download on first launch. If that download depends on routing rules that haven't loaded yet or a proxy that isn't available, startup can get stuck in a dependency loop. In that case, manually install a working set of databases first, then troubleshoot the update path. That's more effective than repeatedly restarting into the same error.

Rule syntax: put GEOSITE before GEOIP

Domain rules classify domains; IP rules classify destination addresses. They answer different questions. A domain belonging to a service doesn't mean its servers are necessarily in a particular country or region. A site may use an overseas CDN, and the same domain can resolve to addresses in multiple regions. Put specific domain rules first, broader IP rules after them, and keep MATCH as the final fallback.

This example assumes your configuration already defines a proxy group named PROXY. Names are case-sensitive, so use the exact name of your group. Don't copy the rules and forget to define the referenced outbound.

mode: rule

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOSITE,cn,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

How each rule matches

1. DOMAIN-SUFFIX defines a specific domain exception. Put it before category rules so a broader category can't match first. example.com is shown here only to demonstrate the syntax.
2. GEOSITE,cn,DIRECT matches the cn category in the domain database. It can match the domain collection without first resolving the domain to its real IP address.
3. GEOIP,private,DIRECT,no-resolve uses the private-address category, which must be supported by your selected data source. Don't assume MMDB mode has exactly the same categories as DAT mode.
4. GEOIP,CN,DIRECT checks the destination IP's location. For a connection that only has a domain name, this rule may trigger a DNS lookup.
5. MATCH,PROXY catches connections that didn't match any earlier rule. It doesn't “figure things out”—it's just the final fallback.

no-resolve is not a DNS leak protection switch

no-resolve means the core won't actively resolve a domain just to match that IP rule. If the connection already has a usable destination IP, the rule may still match. If it has only a domain and no applicable IP, the core moves on to the next rule. Adding it to every GEOIP rule may break direct rules that depend on resolved addresses, sending more connections to MATCH.

fake-ip mode doesn't stop GeoSite from working. The core can associate a domain with its fake IP mapping, but that doesn't mean GEOIP should treat synthetic addresses in 198.18.0.0/16 as the server's real location. When troubleshooting, check the domain, the actual DNS results, and the matched rule. Don't focus on a single address in the connection list.

Still not matching after an update? Use the logs to narrow it down

Change one variable at a time: update the files without touching the rules and confirm the core starts. Then adjust rule order, and only then change geodata-mode or the data source. Changing all three at once makes the logs much noisier without making the cause any easier to find.

To verify the result, make sure the client is in Rule mode, close the target app's existing connections, and send a new request. Existing TCP connections usually won't switch to a different outbound just because a rule or database changed. Browser connection reuse can also skew your results. Test with a domain you're troubleshooting and check the connection record for the matched rule type, rule, and final policy chain.

If you temporarily increase the log level, restore the original setting when you're done. Before sharing logs, redact subscription URLs, access tokens, node credentials, and control API keys. For database issues, the relevant details are the load path and error lines—not your entire account configuration.

Keep maintenance notes and a known-good combination for rollback

• Record the core version: Save the output of mihomo -v so you don't rely on outdated assumptions about field support after a client upgrade.
• Record the data source: Note the repository, download date, categories used, and geodata-mode to help explain changes in rule matches.
• Keep a working configuration: Back up the matching configuration along with the databases. That way, a rollback won't leave new rules referring to old categories.
• Check both update paths separately: Subscriptions handle nodes and configuration; geodata updates handle category files. A success message from one doesn't confirm the other worked.

For a final check, verify three things: the core loads the files from the correct directory, every category referenced by your rules exists, and new connections match the expected policies. Once all three are confirmed, consider optimizing the update schedule and download source. Newer databases aren't necessarily a better fit for your routing needs; keep explicit rules ahead of broad categories.