GeoIP and GeoSite Database Update Guide: Download Sources, Manual Replacement, and Rule Routing

First, understand what GeoIP and GeoSite match

GeoIP and GeoSite can both condense large rule sets into a short condition, but they work with different inputs. GeoIP identifies a country or region from the destination IP address; GeoSite matches domain names against category lists. They are separate databases and cannot replace one another.

Use GeoSite before GeoIP

Most configurations evaluate rules from top to bottom. Domain rules usually reflect business intent more closely than IP geolocation, so they should come first. For example, a service may use CDNs across multiple countries. GeoIP sees only the node address returned by the current DNS lookup, while GeoSite can consistently classify the original domain.

rules:
  - GEOSITE,category-ads-all,REJECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,select a node

These rules block ad categories first, then handle common mainland China domains, use GeoIP as a fallback for mainland China addresses not matched by domain rules, and finally pass everything else to the default policy group. The available labels depend on the selected GeoSite source, so confirm that label names match before switching sources.

Confirm the data format Mihomo actually uses

Clash Meta is now maintained under the Mihomo name. Different clients may bundle different core versions or retain older Clash-style configuration entries. Before updating, open “Settings” → “Core” or “Settings” → “Version Info” and check the core name and version. For command-line deployments, run mihomo -v.

Mihomo's geodata-mode controls how GeoIP data is read. When enabled, it typically reads GeoIP.dat; when disabled, it typically uses the MMDB-format Country.mmdb. GeoSite categories are still provided by GeoSite.dat. Do not assume the core will read a same-named replacement file without checking the mode and working directory.

geodata-mode: true
geodata-loader: memconservative

rules:
  - GEOSITE,private,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,select a node

geodata-loader: memconservative suits environments where lower memory usage matters more. The supported values and behavior may change between core versions, so verify the result through the client's configuration checker or a command-line test. On desktops with sufficient memory, keeping the default generated by the client is usually safer.

no-resolve is not universally required

When a GEOIP rule receives a domain name as its destination, the core may need to resolve it to an IP before matching the region. Adding no-resolve at the end of the rule means that the rule should not trigger an extra lookup. This can reduce unnecessary DNS requests, but it also means the GEOIP rule will not resolve and match a destination whose IP is not yet known.

• The connection already includes a destination IP: GEOIP can match it directly, and no-resolve usually does not prevent a match.
• The destination is still a domain: prefer DOMAIN, DOMAIN-SUFFIX, or GEOSITE rules.
• The configuration relies on GEOIP to evaluate a resolved domain: do not add no-resolve without testing it first.

Configure automatic download sources

Mihomo can use geox-url to specify geodata URLs, while geo-auto-update controls automatic updates. The example below uses GeoIP and GeoSite files from the same release repository to avoid large differences in release timing and classification criteria.

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"

geo-update-interval: 24 is measured in hours, so it checks once every 24 hours. Daily updates are sufficient for desktop clients; setting the interval to one hour or less is unnecessary. Database releases usually change less often than proxy node status, so overly frequent checks only add network requests during startup.

A download source must meet four conditions

1. Matching file format. The GeoIP URL must return a data file supported by the core's current mode; it must not point to a web download page instead of the binary file.
2. Matching filename and content. The geoip entry must point to IP data, while geosite must point to domain category data.
3. Verifiable label definitions. Labels such as cn, private, and category-ads-all must exist in the selected data source.
4. Accessible during core startup. If the first download occurs before the rules take effect, the download path must not depend on that same rule set and create a loop.

Check the configuration before reloading the core

In a command-line environment, use the core's own YAML checker. -d specifies the working directory, which is also where the databases are read; -f specifies the main configuration file. Add quotes when a path contains spaces.

mihomo -d "/opt/mihomo" -f "/opt/mihomo/config.yaml" -t

In a graphical client, open the “Configuration” page, select the active profile, and choose “Check” or “Reload.” Menu names may vary slightly by client version, but the order should remain: save a rollback copy, check the YAML, reload the core, and review the logs. If the logs report a download failure, invalid file format, or missing label, restore the old files first instead of changing several settings at once.

Manually replace the database in an offline environment

Manual replacement is useful when a server cannot reach the download source, an enterprise network blocks external connections, or a specific database version must be pinned. The key is not copying files into the application install directory, but locating Mihomo's working directory. For command-line deployments, the working directory is set by -d; graphical clients usually offer an entry such as “Settings” → “Configuration Directory” or “Settings” → “Application Directory.”

Standard replacement procedure

1. On a network-connected device, download the GeoIP.dat, GeoSite.dat, or Country.mmdb files that match the active configuration.
2. Record the release version and download date, such as 2026-05-28, so you can tell later whether another update is needed.
3. Stop the Mihomo core on the target device and confirm through the tray menu or service manager that it has exited.
4. Open the working directory and rename the old files to GeoIP.dat.bak and GeoSite.dat.bak.
5. Copy in the new files, preserving the capitalization and filenames expected by the core.
6. Run the configuration check, then start the core and watch the first 30 seconds of logs.
7. Run three kinds of tests: private addresses, commonly used mainland China domains, and domains that should use the default proxy.

For Linux service deployments, copy the file under a temporary name first, then replace it with a rename on the same filesystem to reduce the risk of the process reading a partial file. The paths below only illustrate a working directory set by -d /etc/mihomo.

sudo systemctl stop mihomo
sudo cp /mnt/offline/GeoIP.dat /etc/mihomo/GeoIP.dat.new
sudo cp /mnt/offline/GeoSite.dat /etc/mihomo/GeoSite.dat.new
sudo mv /etc/mihomo/GeoIP.dat /etc/mihomo/GeoIP.dat.bak
sudo mv /etc/mihomo/GeoSite.dat /etc/mihomo/GeoSite.dat.bak
sudo mv /etc/mihomo/GeoIP.dat.new /etc/mihomo/GeoIP.dat
sudo mv /etc/mihomo/GeoSite.dat.new /etc/mihomo/GeoSite.dat
mihomo -d /etc/mihomo -f /etc/mihomo/config.yaml -t
sudo systemctl start mihomo

On Windows graphical clients, do not overwrite files while the core is running. Exit the core from the tray menu or quit the client first, then modify the configuration directory. If a file is locked, forcing an overwrite may leave a temporary file behind, while the client continues reading the old database on its next launch.

What routing anomalies appear when the database is outdated

Outdated geodata usually does not crash the client directly. Instead, it causes localized, intermittent routing anomalies. These problems are easy to mistake for unstable nodes because only some CDN addresses or newly added domains may match the wrong policy.

Typical signs of an outdated GeoIP database

• A newly allocated IP range falls through to MATCH instead of matching the expected GEOIP,CN.
• After a cloud provider or CDN changes an address's geolocation, the connection is sent to an unexpected policy group.
• IPv4 matches normally, but newly added IPv6 ranges use the default policy.
• The same domain resolves to different addresses, causing its policy to switch between DIRECT and the default proxy.

Typical signs of an outdated GeoSite database

• After a service launches a new domain, that domain is not added to its existing category.
• The ad category does not cover tracking domains added recently.
• When the configuration references a new label, the core log reports that the corresponding GeoSite category does not exist.
• After a source changes its label structure, old rules still load, but their coverage has changed.

A single domain using the wrong policy does not by itself prove that the database is outdated. The cause could also be rule order, DNS caching, Fake-IP mapping, sniffing settings, or a user-defined override. Check the actual matched rule on the Connections page first, then compare the destination domain, destination IP, and policy group.

Verify rule interaction with logs and connection records

After updating, do not check only the file dates. A more effective approach is to observe which rule real connections match. Open the client's “Connections” page, clear the old records, and visit a private address, a mainland China site, and a site that should use the default policy. The records should show the destination domain, destination IP, rule type, and final policy.

Four recommended test groups

1. Private network: Access a router or LAN service and confirm that GEOSITE,private, GEOIP,private, or an explicit subnet rule matches first.
2. Domain category: Visit a domain with a clearly defined category and confirm that GEOSITE matches it instead of sending it directly to GEOIP or MATCH.
3. IP fallback: For a connection with only a destination IP, verify that GEOIP routes it as expected.
4. Default rule: Choose a domain outside the categories above and confirm that it ultimately enters the policy group specified by MATCH.

In TUN mode, application traffic may initially reach the core as an IP address. Mihomo can use DNS mapping and domain sniffing to recover some domain information, but the result depends on the protocol, encryption method, and client settings. If GEOSITE consistently fails to match, also check TUN, DNS, and sniffing options under “Settings” → “Network” instead of repeatedly changing databases.

log-level: info

rules:
  - GEOSITE,private,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,select a node

info level is usually enough to inspect connections and rule results. Switch to debug only when diagnosing database loading, DNS mapping, or sniffing problems. Restore the original level afterward to avoid accumulating excessive logs.

Common update failures and troubleshooting order

The download succeeds, but the old result is still used after restart

First confirm that the new file was placed in the core's working directory, not the install or download directory. Then check geodata-mode: when the configuration requires MMDB, replacing only GeoIP.dat will not change GeoIP matching. Graphical clients may also manage multiple core directories, so use the log path of the currently enabled core as the reference.

The log says the GeoSite label does not exist

This usually means the rule labels and data source use different definitions. Locate the failing rule first, such as GEOSITE,category-ads-all,REJECT, then check whether the current source provides that category. Do not treat similar label names as equivalent; different maintenance projects may merge, split, or rename categories.

Automatic update times out during startup

Restore the update interval to 24 hours first, and confirm that the URL directly returns a data file. For a first deployment, place the database manually in a network-connected environment before starting the core. That way, existing rules can still load if the remote update temporarily fails. On servers, also check that the systemd service user has write permission for the working directory.

A large amount of traffic switches to other policies after the update

Immediately restore the complete backup, then compare the old and new sources, label coverage, and rule order. A database update can change classification results, but do not also modify the rule set, DNS, and TUN settings without records. Change one variable at a time so you can determine whether the discrepancy comes from the data or the configuration.

Establish a repeatable maintenance cycle

Personal desktops can use daily automatic checks and a monthly manual review. For long-running servers, record the core version, database sources, release dates, active mode, and most recent verification result. When routing anomalies occur, these five details are more useful than simply noting that the databases were “updated.”

• Daily: let geo-auto-update check at a 24-hour interval.
• Monthly: verify that the GeoIP and GeoSite sources are still maintained, and spot-check four rule categories.
• After upgrading the core: reconfirm geodata-mode, filenames, and the working directory.
• When changing sources: check the label list first, then adjust the rules; do not overwrite production files directly.
• When anomalies occur: save the connection records, matched rules, destination IPs, and log timestamps.

Maintaining GeoIP and GeoSite is not about chasing the highest update frequency. It is about keeping the data format, label definitions, rule order, and core working directory aligned. Automatic updates retrieve files, manual backups provide rollback, and connection records verify the final routing. Only when all three are in place is the database update truly complete.