How to Update GeoIP and GeoSite Databases: A Complete Guide to mihomo Geographic Rules

First, distinguish GeoIP, GeoSite, and the rules themselves

GeoIP and GeoSite are both datasets queried by the rules engine, but they operate on different inputs. GeoIP uses a destination IP address to identify a country, region, or private network range; GeoSite uses a domain name to identify its site collection. GEOIP and GEOSITE in a configuration are only query directives—the actual classifications come from local database files.

Consider a single request. When the destination is a domain, mihomo can first match it against domain rules or a GeoSite category. If no earlier rule matches, a later GEOIP rule may trigger DNS resolution and then query the IP database with the resolved address. The strategy group ultimately used is determined by the first matching rule in the list. The database only answers “which collection does this domain or IP belong to?” It does not choose whether to go direct, use a proxy, or reject the connection.

GeoSite is not a top-level domain list. For example, GEOSITE,cn queries a domain collection curated by the data provider; it does not simply match addresses ending in .cn. A mainland China service using .com may also be included, depending on the current database version.

geodata mode vs. MMDB mode

What happens when geodata mode is enabled

With geodata-mode: true, mihomo uses geoip.dat for GEOIP classifications and geosite.dat for GEOSITE classifications. Dat files can contain multiple labeled collections, so common tags such as CN, LAN, and other GeoSite labels map to entries inside the file.

geodata-mode: true
geodata-loader: memconservative

geodata-loader controls how geodata is loaded. standard tends to load data in advance, keeping repeated matching more predictable but using more memory; memconservative favors on-demand loading and suits routers or containers with limited memory. On a device with about 100 MB of available memory, start with memconservative, then decide whether to change it after observing rule-loading and first-match times.

What happens when geodata mode is disabled

With geodata-mode: false, GEOIP lookups generally use country.mmdb. MMDB is a database format designed for IP lookups and cannot replace GeoSite domain classifications. If the configuration contains GEOSITE rules, geosite.dat must still be available.

geodata-mode: false

Neither mode is universally faster on every device. Database size, rule count, storage performance, and loader settings all affect the result. On desktop systems, focus more on data-source coverage and update frequency; on low-memory devices, also monitor mihomo’s resident memory after startup. After switching modes, fully restart the core instead of merely reloading the configuration in the client.

• If your rules make extensive use of GEOSITE and Dat labels, geodata mode is usually the better choice.
• If the existing rules mainly use GEOIP,CN and the available data source only provides MMDB, you can continue using MMDB mode.
• Do not rename geoip.dat to country.mmdb; different extensions indicate different internal formats.
• Keep the original database files before switching modes so you can restore them if classifications become abnormal or startup errors occur.

Configure automatic database updates

mihomo can retrieve GeoIP, GeoSite, MMDB, and ASN data from specified URLs. The key fields are geo-auto-update, geo-update-interval, and geox-url. The update interval is measured in hours; setting it to 24 checks for updates once every 24 hours. Geographic classifications rarely need minute-by-minute refreshes, and a daily check covers most desktop and home-gateway use cases.

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"
  asn: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/GeoLite2-ASN.mmdb"

Even with geodata mode enabled, you can keep an MMDB URL configured for a future switch. The file actually used by the current rule path is still determined by the mode and rule type. If the client merges settings through an override, keep these fields at the top level; do not indent them under dns, rules, or proxy-groups.

Should update requests use a direct connection or a proxy?

Whether a database download succeeds depends on whether the core can reach the data URL at runtime. Some clients download files early during core startup, before proxy policies are fully available; others send update requests through the current rules. If the logs show repeated timeouts, first confirm that the URL is reachable in a browser, then check DNS, system time, outbound rules, and whether the client bypasses the core process.

For troubleshooting, open “Logs” → “Log level” → “Info” or “Debug,” then restart the core. A normal process usually logs geographic data downloads, writes, or loads. If the connection still times out after 30 seconds, do not keep clicking Update. First identify which strategy group matched the data domain, then check whether its current node is available.

Manually replace GeoIP and GeoSite files

Manual replacement is useful when automatic updates fail, the device cannot access the data source directly, or a specific data version must be pinned. The key is finding mihomo’s actual working directory. Common command-line defaults are ~/.config/mihomo/ on Linux and macOS and %USERPROFILE%\.config\mihomo\ on Windows. If the startup command uses -d, use the directory specified after -d.

Graphical clients often use their own application-data directory and may not read the default paths above. Open the actual location from “Settings” → “Configuration directory” or “Settings” → “Application directory,” then confirm it against the database path in the logs. Do not search only for files with matching names in the file manager; an old directory and the active runtime directory may both exist.

1. Record the current core version, the geodata-mode setting, and the working directory.
2. Stop the mihomo core to prevent open file handles during replacement.
3. Rename the original file for backup, such as changing geosite.dat to geosite.dat.bak.
4. Copy in the new file and keep the names expected by the core: geoip.dat, geosite.dat, country.mmdb, or GeoLite2-ASN.mmdb.
5. Restart the core and check the logs for unsupported formats, missing labels, or file-read failures.
6. Use a clear test rule to verify the match result instead of checking only whether the client displays “Running.”

If replacement produces load GeoSite failed, invalid database, or a missing-label error, restore the backup first, then verify the data format and configuration mode. A downloadable file is not necessarily suitable for the current core; some sources use different label names, so GEOSITE,cn may work while more granular categories do not.

How to write GEOIP and GEOSITE rules

A readable baseline order

mihomo evaluates rules from top to bottom and stops at the first match. Put more specific rules before broader geographic rules, and use MATCH as the final fallback. The Node selection and Mainland China direct names below must match strategy groups that actually exist in the configuration.

rules:
  - DOMAIN,api.example.org,Node selection
  - DOMAIN-SUFFIX,example.org,Node selection
  - GEOSITE,category-ads-all,REJECT
  - GEOSITE,cn,Mainland China direct
  - GEOIP,LAN,DIRECT,no-resolve
  - GEOIP,CN,Mainland China direct
  - MATCH,Node selection

The first exact-domain rule has the highest priority. The second covers that domain and its subdomains. Only then do GeoSite classification and GeoIP lookup run. If GEOSITE,cn,Mainland China direct is placed before a rule for a mainland China site that needs special handling, the specific rule may never match.

Understand the limits of no-resolve

no-resolve tells an IP-based rule not to actively resolve a domain just for matching. It suits rules such as GEOIP,LAN,DIRECT,no-resolve that mainly handle known destination IPs and can reduce unnecessary DNS queries. However, if the destination is still a domain and no earlier rule matches, the GEOIP rule may be skipped because no destination IP is available.

Do not mechanically append no-resolve to every GEOIP rule. If GEOIP,CN is an important fallback for mainland China traffic, test it together with the DNS mode, sniffing results, and actual connection types. TUN mode gives mihomo a broader range of traffic, but it does not change rule order or database lookup logic.

How to verify that the database and rules are working

Verification should check both that the file was loaded and that the request matched the intended rule. A changed database timestamp does not prove that rule order is correct; a successful connection does not prove that traffic used the expected strategy group.

Test a GeoSite rule

1. Temporarily direct the target category to an easy-to-recognize strategy group, such as Mainland China direct.
2. In “Logs” → “Log level,” select “Info” or “Debug.”
3. Clear the browser’s existing connections and revisit the test domain.
4. Check the rule type, matched label, and final strategy group in the logs.
5. Restore the production configuration after testing so temporary rules do not remain indefinitely.

Avoid cache interference when testing GEOIP

Browsers may reuse HTTP/2 or HTTP/3 connections, and DNS results may come from the system, browser, or mihomo cache. After changing rules, first select “Configuration” → “Reload” in the client, then close the relevant tabs and wait for old connections to end. Restart the browser or core if necessary, and observe the logs through a new connection.

If one domain resolves to multiple IPs, its GeoIP classification may change with the resolved address. This is especially common with CDN services: different networks, DNS servers, and times may return addresses from different regions. For these services, DOMAIN, DOMAIN-SUFFIX, or GEOSITE rules are generally more reliable than relying entirely on GEOIP.

Common issues and troubleshooting order

GeoSite label not found

First confirm that geosite.dat was loaded by the core from the current working directory, then verify the label spelling. Labels are defined by the data source and cannot be inferred freely from service names. If the log reports an error for only one label, the current dataset usually lacks that category; if every GEOSITE rule fails, the more likely causes are the file path, file format, or loading process.

The update succeeded, but rule results did not change

Some clients need a core restart to load newly downloaded files. First select “Settings” → “Core” → “Restart core,” then check the data-file path in the startup log. If the log still points to another directory, inspect the -d startup argument and whether the client runs the subscription configuration in a separate directory.

Field error while parsing the configuration

This usually means the core is outdated or the client launched a different mihomo binary than expected. Run mihomo -v and compare it with the version shown under “Settings” → “Core” in the client. Before upgrading the core, confirm that the client supports the corresponding core interface. If you cannot upgrade yet, remove fields unsupported by the old version rather than moving them to another YAML level.

Some applications still bypass geographic routing in TUN mode

First check whether the connection entered mihomo, then check whether the domain is visible. GEOSITE cannot match directly when only a destination IP is available; the connection may require sniffing to recover the domain or rely on a GEOIP rule. Also check process rules and IP-CIDR rules that appear before the geographic rules, because the first match ends evaluation.

A complete troubleshooting sequence is: confirm the core version, confirm the working directory, confirm database-load logs, confirm rule order, confirm DNS or sniffing results, and finally check the strategy-group exit. Following this order separates “the database did not update” from “the rule did not match” as two independent problems.