How to Update Clash GeoIP and GeoSite Databases: Configure geox-url and Write GEOSITE Rules

Check the core first, then distinguish GeoIP from GeoSite

First, check the client’s About or core information page to see which core is running. Clash is commonly used to refer to a proxy core and its ecosystem; graphical clients manage configuration and system proxy settings, and launch the core. The geox-url, GEOSITE, and automatic update examples in this guide are for mihomo, the project formerly known as Clash Meta. They don’t apply to every legacy Clash core.

Identify which database you need before updating a file. GeoIP maps IP address ranges to countries, regions, and other groups. GeoSite groups domains by service or purpose. These databases provide data for rule matching; they don’t provide proxy nodes or replace subscription links. Updating a database won’t bring expired nodes back online.

Check which categories the data source includes before writing a category name. cn is a common example, but some trimmed data packages may not include it. GeoSite categories are usually lowercase; check the data source documentation for categories with attributes. Don’t guess a label from a website’s name and then assume a failed load is a network issue.

Find the actual data directory to avoid replacing the wrong files

First find the working directory used by the running core. The command-line -d option specifies the configuration and data directory. Graphical clients usually have their own application data directory, while service mode may use a different account or path. The installation folder, downloads folder, and active configuration directory aren’t necessarily the same.

1. Open the client’s directory menu and look for options such as “Configuration directory,” “Data directory,” or “Open application directory.” Menu labels vary by client and version, so check the interface you’re using.
2. Check the core startup log or process arguments to see where -d points. Don’t overwrite a file just because you found one with the same name.
3. Look in that directory for geosite.dat, geoip.dat, or Country.mmdb. Note the file size, modification time, and active configuration.
4. Distinguish the raw subscription from the final runtime configuration. After the client merges configurations, the effective settings may differ from what you see in the subscription editor.

When running the command-line core from a separate directory, you can specify the path explicitly. The examples below use a Linux or macOS terminal and assume mihomo-data/config.yaml is already in the current directory. The first command checks the version; the second validates the configuration. Validation doesn’t keep the core running as a proxy.

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

Configure geox-url and scheduled updates

Add the update fields at the top level of the YAML, alongside rules and dns. YAML uses indentation to define nesting; don’t indent these fields under dns or a proxy node. The following snippet is meant to be merged into an existing configuration, not used as a complete configuration with proxy nodes and policy groups.

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"

• geodata-mode: true: Use GeoIP data in DAT format for GEOIP matching. Setting this to false generally uses the MMDB path; it doesn’t turn GeoSite on or off.
• geo-auto-update: true: Enable scheduled updates for the core’s geodata.
• geo-update-interval: 24: Set the update interval to 24 hours; this doesn’t mean updates happen at a fixed time each day.
• geox-url: Specify download sources for each data type. Setting a source doesn’t download the files immediately.

Configure data sources for the mode you actually use. The example lists both DAT and MMDB URLs to show how they correspond; DAT mode doesn’t require all three files on every update. mmdb is a configuration key. The example download URL ends in lowercase country.mmdb, while the common local filename is Country.mmdb. Don’t mix them up when replacing files manually.

After saving, reload the configuration and check the logs. If the client has an option such as “Update Geo data,” use it to trigger an update. If it doesn’t, don’t assume a restart will overwrite existing databases. Automatic updates are scheduled by the core; to replace files immediately, use the offline method in the next section.

First make sure the download URL is reachable from your current network. GitHub release assets may redirect, so use a command-line download option that follows redirects. The client’s system proxy setting doesn’t guarantee that the core itself will use the same route to download files. If a download times out, check the log for the domain, connection error, and proxy route before switching to a trusted data source.

Manually replace geosite.dat and geoip.dat

Download to temporary files first, then stop the core before replacing the files. Don’t write to a file while the core is reading it, and don’t simply rename a browser’s “Save as” result to a database filename. A downloaded login or error page isn’t usable data, even if its extension is .dat.

The examples below continue to use the separate directory from earlier and demonstrate DAT mode only. First, download the files: -f treats HTTP errors as failures, and -L follows redirects. Continue only after both commands succeed; don’t ignore terminal errors.

curl -fL --retry 2 \
  "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat" \
  -o "./mihomo-data/geoip.dat.new"

curl -fL --retry 2 \
  "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat" \
  -o "./mihomo-data/geosite.dat.new"

Next, quit the graphical client or stop the relevant core service, and make sure it won’t restart automatically. These commands assume both data files already exist and the backup filenames haven’t been used. For a new installation without the original files, skip the corresponding backup commands. Keep a separate backup for every update so you don’t overwrite your last working copy.

cp "./mihomo-data/geoip.dat" "./mihomo-data/geoip.dat.before-update"
cp "./mihomo-data/geosite.dat" "./mihomo-data/geosite.dat.before-update"

mv "./mihomo-data/geoip.dat.new" "./mihomo-data/geoip.dat"
mv "./mihomo-data/geosite.dat.new" "./mihomo-data/geosite.dat"

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

After validation succeeds, start the core and check the initial load and request logs. Configuration validation catches only some errors; it can’t replace runtime testing. If you see a missing category, file read failure, or parsing error, stop the core, restore the backup, and then check the source and file format.

In MMDB mode, download a file in the matching format and replace Country.mmdb in the actual data directory. Don’t rename geoip.dat to Country.mmdb; they use different internal formats. Linux filenames are case-sensitive, and the running account must retain read access after replacement.

Write GEOSITE and GEOIP rules

Make sure the client is in Rule mode before changing the rule order. Rules are checked from top to bottom, and the first match usually ends the search. Global mode doesn’t choose an outbound for each request based on this list; TUN mode captures traffic and doesn’t replace Rule mode.

The examples below assume the existing configuration defines a policy group named “Proxy Select.” DIRECT is a built-in direct outbound, so you don’t need to create it. “Proxy Select” must exactly match the actual group name. The example domains illustrate the syntax; add or remove rules to suit your needs.

mode: rule

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

Put specific exceptions before broad category rules

Add domains that need special handling before category rules. The first DOMAIN-SUFFIX rule matches the specified domain and its subdomains; the second handles domains in the GeoSite cn category; the third matches IP ranges in mainland China. The final MATCH rule catches everything else. Don’t put MATCH at the top, or the geodata rules below it will never run.

Understand the trade-offs of no-resolve

Think of no-resolve as “don’t resolve a domain just for this IP rule.” If the destination is already an IP address, GEOIP matching can still apply. If a request has only a domain and no destination IP is available, this rule won’t trigger an extra lookup for matching, so the request may fall through to MATCH. Adding it can reduce unnecessary DNS queries, but it doesn’t guarantee that every domain in mainland China will match GEOIP.

A domain category doesn’t prove where a server is located. A domain may use a global content delivery network, and the same service may appear in multiple domain categories. GeoSite classification and GeoIP location matching answer different questions. Use domain rules when you want to classify services, and IP rules when you want to match destination address ranges.

Verify rule matches after updating, not just file timestamps

First, check new requests in the client’s connections panel to see which rule and outbound they use. A newer file timestamp only confirms that the file was written; it doesn’t mean the running core reloaded it or that your test request went through that core. If the browser reuses an old connection, close the relevant tabs or connections before making a new request.

1. Confirm that the modified configuration is active, then check geodata-mode and the rule order in the runtime configuration.
2. Check the logs for data loading errors, especially messages about missing files, insufficient permissions, or missing categories.
3. Choose a domain known to belong to the target category and check whether the connection details show GEOSITE, GEOIP, or a domain rule that appears earlier in the list.
4. Confirm that the outbound is the expected DIRECT or policy group, then check which node the group currently selects.
5. To test a connection with only a destination IP, verify GEOIP separately. Don’t use a single domain request to claim that both databases are working.

When testing from a terminal, specify the local proxy port explicitly. The example assumes mixed-port is set to 7890 in the existing configuration; if the port differs, use the value shown in the client. This command confirms that the request enters the proxy chain, but a successful response alone doesn’t prove which geodata category matched. Check the connections panel too.

curl -I --proxy http://127.0.0.1:7890 https://example.com

Troubleshoot update failures by error type

Distinguish geodata from rule-providers

First check whether the rule uses GEOSITE or RULE-SET. rule-providers load separate rule sets, each with its own download URL, format, and update interval. Configuring geox-url won’t also update every rule provider; likewise, updating a rule provider doesn’t replace geosite.dat.

Keep changes small and easy to roll back

Change one thing at a time: update the database and verify existing rules before adding categories or changing rule order. If something breaks, restoring the relevant data file and configuration makes it easier to find the cause than reinstalling the client, changing DNS, and enabling TUN all at once. For more on configuration merging or traffic capture, see the setup guide. For connection issues, follow the steps in Troubleshooting.