GeoIP and GeoSite Database Updates: geox-url Configuration and Rule Syntax

Understand GeoIP, GeoSite, and rule providers

A website using the wrong proxy route doesn’t necessarily mean the proxy node is at fault. At least three parts of the routing chain affect the outcome: the domain or destination IP associated with the connection, the order of rules in your config, and the data those rules reference. Updating Geo data addresses only the last item. It won’t replace DNS troubleshooting or add new rules to your config.

This guide is for Clash clients running the mihomo core. Clash is a common name for the client ecosystem, but it doesn’t mean every core supports the same fields. Older Clash cores can’t use the GEOSITE and automatic update settings shown here as-is. Before making changes, check the client’s core information to confirm it’s actually running mihomo—don’t rely on the window title alone.

GeoSite categories don’t identify a website’s purpose in real time; they’re domain lists maintained by data providers. GeoIP isn’t a precise location tool, either: cloud hosting, CDNs, cross-border routing, and IP address transfers can all make a geographic classification differ from how you intend to route traffic. For important services, explicit domain rules are usually more predictable than routing based only on country-level IP data.

Configure geox-url: data sources and automatic update intervals

The snippet below is a top-level section to merge into an existing config, not a complete subscription with proxy nodes. It selects GeoIP DAT mode, sets download URLs for GeoIP, GeoSite, and MMDB data, and enables automatic Geo data updates every 24 hours. The example uses release assets from MetaCubeX’s meta-rules-dat. Before using these URLs, make sure they’re reachable from your network.

geodata-mode: true
geodata-loader: memconservative

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"

Check each field carefully—intervals are in hours, not seconds

• geodata-mode: true: Uses GeoIP DAT data for GEOIP. Set it to false to use MMDB data. This setting does not enable or disable GeoSite as a whole.
• geodata-loader: memconservative: Uses a DAT loader that consumes less memory. It doesn’t change rule priority or speed up downloads.
• geo-auto-update: true: Enables scheduled Geo data updates in the core. The client may also offer a separate manual update option.
• geo-update-interval: 24: The unit is hours, so this means 24 hours—not 24 seconds. Scheduled updates run while the core is running; downloads won’t continue while the computer is off.
• geox-url: Sets the data sources. Changing a URL doesn’t replace the data currently in use; an update must run and the new data must load.

The example also keeps the mmdb URL for a possible switch to MMDB GeoIP mode later. This doesn’t mean a single GEOIP lookup checks both DAT and MMDB. MMDB data that uses only country codes also can’t use custom categories available only from some DAT data sources.

Keep update settings in subscription-based clients

Many clients download a remote subscription and then generate a runtime config. Editing the generated file directly may work temporarily, but your changes can be overwritten the next time the subscription updates. First, identify the three separate layers: the original subscription, client overrides, and the final config used by the core.

1. Note your current setup. Record the mihomo version, active config name, and Geo data directory from the client’s core information or startup log. Use the client’s “Open config directory” option or equivalent to find the files. Don’t assume another client uses the same paths.
2. Back up your working settings. Save your current overrides and existing databases. Keep files containing subscription URLs or proxy passwords on your own device—never post them in public forums.
3. Update the persistent config layer. If the client supports Merge, overrides, or extended config, add the top-level fields above there. If you maintain your own local YAML file, edit that file directly.
4. Check the final config. After reloading, confirm the runtime config still contains geodata-mode, geox-url, and the update interval. Seeing the fields in an editor doesn’t prove they made it into the core.
5. Run an update. Use the client’s Geo data update feature and check the core log. Menu names vary between clients; “update subscription” is not the same as “update Geo data.”

If your client doesn’t have a Geo data update button, keep automatic updates enabled or use the offline replacement steps below. When required data is missing on first launch, the core may try to download it. If a working proxy isn’t available yet, this can create a startup deadlock: the core needs data to start, but needs a proxy to download the data. Preparing the files offline is often more straightforward than repeatedly restarting.

How to write GEOIP and GEOSITE rules

The rules below assume your existing config has a policy group named Proxy Select. If your group has a different name, update it in the rules too. DIRECT is a built-in direct-connection policy; you don’t need to create it. Merge these lines into your existing rules list rather than adding a second rules key.

mode: rule

rules:
  - DOMAIN,example.com,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOSITE,geolocation-!cn,Proxy Select
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,Proxy Select

Rules are evaluated from top to bottom; the first match wins

DOMAIN,example.com,DIRECT is an exact-domain rule, shown here to illustrate that exceptions for individual sites should come before broader rules. The next two GeoSite rules select a route by domain category. Make sure your data source includes the cn and geolocation-!cn categories. If you switch to a smaller database, check whether those categories are still available.

GEOIP,CN,DIRECT,no-resolve checks whether a known destination IP belongs to the CN category. The trailing no-resolve means this IP rule won’t trigger an extra DNS lookup just to match. A connection with an available destination IP can still match the rule. It doesn’t disable DNS or make all requests bypass the DNS module.

The final MATCH rule catches connections that didn’t match anything above it. If it’s on the first line, the GeoSite and GeoIP rules below it never get a chance to run. Global mode forwards traffic according to the global policy, so it can’t be used to verify this rule order.

GeoSite can’t match a domain that isn’t available

GeoSite rules may not match if an app connects directly to an IP address or the core can’t associate a domain with the traffic. TUN is just one way to capture traffic; it doesn’t mean every connection automatically carries a domain. Check whether DNS is using the expected route, whether the Fake-IP mapping is valid, and whether sniffing needs to be enabled and configured correctly. Replacing GeoSite files won’t restore domain information that isn’t there.

How to verify an update is actually working

“Download complete,” “file replaced,” and “new connections match the updated data” are three different checkpoints. A changed file timestamp alone doesn’t prove the current core has loaded the new data. And being able to open a website doesn’t prove it used the intended route.

1. Check the download and load results. Review the logs after the update and distinguish network timeouts, download failures, data parsing errors, and missing categories. Log messages vary by core version, so note the exact error and when it occurred.
2. Check the run mode and rules. Switch to Rule mode and confirm the final config places Geo rules before MATCH and that the target policy group exists.
3. Start a fresh test connection. Close existing connections in the test app, then make a new request. Established TCP connections usually won’t switch to a different proxy route just because the database was updated.
4. Inspect the connection details. Check the destination domain, destination IP, matched rule, and actual route. If the connection matched an earlier DOMAIN-SUFFIX rule, it never reached the Geo rules below it.

You can temporarily increase log verbosity while troubleshooting, then restore your usual level to avoid logging large amounts of connection data. Before reporting an issue, remove subscription URLs, access tokens, and private domains. The core version, relevant rules, data source, and surrounding error messages are usually enough to narrow it down.

Offline replacement, rollback, and update cadence

When the core can’t download data during startup, offline replacement is a repeatable fix. First download the required file format from your chosen data source, then use the client to confirm which directory the core actually uses. Don’t guess based on the installation directory: desktop apps, system services, and portable setups may use different working directories.

1. Back up the current data files and note their source and download date.
2. Stop the core that’s actually running. In service mode, make sure the background service has stopped too—not just the app window.
3. Replace the files using their original names, such as geoip.dat, geosite.dat, or Country.mmdb, and make sure the account running the core can read them.
4. Start the core, check the load logs, then use a new connection to verify the rule match.
5. If parsing fails or traffic is routed unexpectedly, stop the core and restore the backup. Then check for differences in file format, categories, and data source.

A downloaded file may actually be a login page, rate-limit notice, or error document. Renaming it to .dat won’t make it usable. First confirm that the download came from the expected release asset, then investigate the core error. Never replace a GeoIP file with a GeoSite file; sharing a file extension doesn’t make their contents interchangeable.

For routine maintenance, start with a 24-hour interval; there’s no need to download the data every hour. If a site is routed unexpectedly, check the matched rule and domain information first. Then decide whether to update the data, add an exception for that site, or fix the DNS route. Isolating the problem to the right part of the setup makes it easier to keep a working baseline than repeatedly replacing the entire config. For more field details, see the Technical Reference; for connection setup and the basics, continue with the Setup Guide.