Why Did Clash Meta Rebrand as mihomo?

If you've been using the Clash Meta core for a while, you've probably noticed the wave of changes that swept through the ecosystem between late 2023 and early 2024. The original Clash project was archived and officially stopped receiving updates, leaving the community-driven Clash Meta as the de-facto successor. After a period of rapid development, the project was relaunched in 2024 under the new name mihomo. This wasn't just a cosmetic rename — it marked a deep architectural overhaul:

• The codebase was moved to a standalone repository, fully decoupled from the legacy Clash code
• The YAML config format gained many new fields while maintaining backward compatibility
• The DNS module was rewritten with support for DoH3, QUIC, and other modern protocols
• The rule engine introduced rule-set external rule providers, delivering a massive performance boost
• TUN mode (Mixed Port) became significantly more stable and gained full IPv6 support

For users still running old Clash.Meta (v1.x era) config files, switching to mihomo isn't as simple as dropping in the new binary. Certain config fields have been deprecated or changed, and a direct swap can leave you with a broken proxy or a core that refuses to start. This guide covers every detail you need to check and update during migration.

Before You Upgrade

Back Up Your Config

Before touching anything, make a backup of your config.yaml and any custom rule files. The mihomo config lives in the following locations by default:

• Windows: %USERPROFILE%\.config\mihomo\config.yaml
• macOS / Linux: ~/.config/mihomo/config.yaml

Check Your Current Core Version

Run the following commands in your terminal to confirm which core version you're currently on:

# For old Clash / Clash.Meta binary
./clash -v

# For mihomo binary
./mihomo -v

If the output contains the word mihomo, you're already on the new core — feel free to skip ahead to the new-features section. Otherwise, read on.

Config File Compatibility Check

mihomo is largely backward-compatible with the old Clash.Meta YAML format, but a handful of fields require close attention. Go through the following checklist before starting the core.

Deprecated and Changed Fields

Changes to the TUN Section

If you were using TUN mode, there are some notable differences between the old Clash.Meta syntax and the mihomo equivalent. Here's what a typical legacy config looks like:

# Old Clash.Meta TUN config
tun:
  enable: true
  stack: system
  dns-hijack:
    - 198.18.0.2:53
  auto-route: true
  auto-detect-interface: true

And here's the recommended mihomo config that unlocks the full feature set:

# mihomo recommended TUN config
tun:
  enable: true
  stack: mixed         # mixed mode offers best compatibility
  dns-hijack:
    - any:53           # intercept all DNS queries
  auto-route: true
  auto-detect-interface: true
  strict-route: true   # prevent traffic bypassing TUN

Changes to the DNS Section

The DNS module in mihomo supports more upstream resolver types, and the priority logic for nameserver-policy has been subtly adjusted. Key things to review:

• Remove any enhanced-mode: redir-host settings and replace them with fake-ip
• If you use fake-ip-filter, make sure the list covers domains that shouldn't use fake IPs — NTP servers, games, and P2P are common ones to include
• Keep at least one reliable DNS server in your nameserver list alongside a DoH endpoint (e.g., https://1.1.1.1/dns-query) for encrypted fallback

# Recommended DNS section for mihomo
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "+.lan"
    - "+.local"
    - "time.*.com"
    - "ntp.*.com"
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

Enabling mihomo's New Features

External Rule Sets with rule-providers

rule-providers is one of the most valuable additions in mihomo. Instead of pasting hundreds or even thousands of domain rules inline inside the rules section, you can point mihomo at external URL-based or local file rule lists. The performance difference is dramatic — startup time drops from several seconds to near-instant, and memory usage falls substantially too.

# Define external rule providers
rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400
  cn-direct:
    type: http
    behavior: ipcidr
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/cncidr.txt"
    path: ./ruleset/cncidr.yaml
    interval: 86400

# Reference rule providers in rules section
rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,cn-direct,DIRECT
  - MATCH,Proxy

Sub-Rules: Nested Rule Groups

mihomo introduces the sub-rules field, which lets you nest rule groups inside one another. This keeps your main rule list short and readable while enabling much finer-grained traffic routing — for example, you can first split by region, then further subdivide by application type. It's a major quality-of-life improvement for anyone managing complex configs.

Keeping GeoSite and GeoIP Databases Up to Date

mihomo relies on GeoIP2 and GeoSite databases for accurate geo-based rule matching. If your databases are stale, rule accuracy will degrade over time. You can configure automatic updates directly in the config file:

geodata-mode: true
geox-url:
  geoip: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
  geosite: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
  mmdb: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

Common Migration Errors and How to Fix Them

cannot unmarshal Error on Startup

This type of error almost always points to a YAML field type mismatch or a deprecated field that mihomo no longer accepts. To resolve it:

1. Read the error message carefully — the line X, column Y indicator tells you exactly where the problem is
2. Cross-reference that location with the deprecated fields table above and remove or replace the offending field
3. Run your config through an online YAML validator to rule out syntax errors unrelated to mihomo

DNS Loop / Total Loss of Connectivity

When TUN mode is enabled, misconfigured dns-hijack or fake-ip-filter settings can cause DNS queries to be intercepted by the proxy itself, creating a resolution loop that takes down all traffic. Work through this checklist:

• Confirm that dns.enable: true is set
• Add mihomo's External Controller address (e.g., 127.0.0.1) to your direct-connect list so it never goes through the proxy
• Add +.local and +.lan to fake-ip-filter to exclude local network traffic

TUN Mode: Insufficient Permissions

Creating a TUN device on Linux and macOS requires elevated privileges. Here's the recommended approach for each platform:

• macOS: Use a GUI client that ships with built-in mihomo support — the permission prompt is handled automatically, so no manual sudo is needed
• Linux: Grant the mihomo binary the cap_net_admin capability instead of running as root: sudo setcap cap_net_admin=ep /usr/local/bin/mihomo
• Windows: Run as Administrator, or use a GUI client that handles privilege elevation for you

Rule Provider Download Timeout on First Start

The first time mihomo starts with rule-providers configured, it needs to download all remote rule files. On a slow connection this can push past the default timeout. A few ways to handle this:

1. Specify a local path for each rule provider and pre-download the files manually before starting mihomo
2. Use jsDelivr CDN-accelerated URLs for rule files — they're generally faster and more reliable for users worldwide
3. Increase the timeout value (defaults to 5 seconds; bumping it to 30 seconds usually solves the issue)

Verifying the Migration

Once you've updated your config and restarted mihomo, run through these checks to confirm everything is working correctly:

1. Open the mihomo Web UI (default: http://127.0.0.1:9090/ui) and verify that the core version shown is mihomo
2. Go to the Proxies tab and confirm all your nodes have loaded successfully
3. Run a latency test to make sure nodes are reachable
4. Enable TUN mode and try opening a website that should route through the proxy — confirm traffic is going through correctly
5. Try a domestic or direct-access site and verify that it bypasses the proxy as expected

If all five checks pass, you're done — congratulations! You're now running the most actively maintained core in the Clash ecosystem.

The Core Is Only Half the Story

A lot of users complete the core migration and then continue using an outdated GUI client from years ago — which means they can't actually take advantage of what mihomo brings to the table. Common pain points with legacy clients include:

• No visual management for rule-providers — every change requires hand-editing YAML
• Clunky TUN mode controls that sometimes require restarting system services
• The core version is locked in place, so you miss out on mihomo bug fixes automatically
• Outdated UI with no real-time latency graphs, bandwidth monitoring, or modern dashboards
• Subscription management that can't auto-select the fastest node per group

If that sounds familiar, it might be time to pair your new core with a client that was actually built for it. Our Clash client is designed from the ground up for the mihomo core — it handles one-click core updates, visual rule management, and TUN mode configuration through a clean interface, so you never have to touch a YAML file to do what this guide describes.

→ Download Clash for free and get up and running on Windows, macOS, Android, iOS, or Linux in under 10 minutes.