Clash Meta to Mihomo Core Migration Guide: Complete Upgrade Tutorial

Why You Need to Migrate from Legacy Clash Core to Mihomo

If you are still running the original Clash Core released before 2022 — the version maintained by Dreamacro — this guide is essential reading. The upstream Clash project was officially archived in November 2023, with its GitHub repository set to read-only. This means your client will never receive another security patch, bug fix, or new feature update.

At the same time, the proxy protocol landscape has moved on rapidly. More and more service providers are rolling out next-generation protocols such as VLESS + REALITY, Hysteria2, and TUIC v5 — none of which the legacy Clash Core can handle. If you are seeing a wall of "connection failed" or "unsupported protocol" errors in your node list, an outdated kernel is almost certainly the culprit.

Mihomo (formerly Clash Meta) is the most actively maintained Clash kernel fork today, developed by the MetaCubeX team. It preserves full backward compatibility with existing Clash configuration syntax while adding native support for REALITY, Hysteria2, TUIC v5, Shadowsocks 2022, and more. It also resolves numerous memory leaks and connection stability issues present in older builds. Upgrading to Mihomo is the most straightforward way to keep the Clash experience alive and up to date.

Preparation Before Upgrading

Before diving into the upgrade process, take five minutes to complete the following steps. A little preparation goes a long way toward preventing data loss or a broken configuration mid-upgrade.

Step 1: Back Up Your Existing Config File

The Clash configuration file is typically named config.yaml and lives in the following default locations:

• Windows: %USERPROFILE%\.config\clash\ or the profiles\ folder inside your client's data directory
• macOS: ~/.config/clash/
• Linux: ~/.config/clash/

Copy the entire clash config folder to your desktop as a backup. This is the single most important step — even if something goes wrong during the upgrade, you can always restore the old config and roll back.

Step 2: Identify Your Client Type

The Mihomo kernel itself is a command-line program. Most users interact with it through a GUI client that bundles the kernel under the hood:

If you are already using Clash Verge Rev or FlClash, you're in luck — these clients ship with Mihomo out of the box. All you need to do is keep the client updated to the latest version; no manual kernel replacement is needed.

If you are on the legacy Clash for Windows or ClashX, follow the manual steps below.

Windows: Replacing the Mihomo Kernel

Swapping the kernel on Windows is straightforward and breaks down into three steps: download the new kernel, replace the file, then restart the client.

Step 1: Download the Mihomo Kernel

Head to the Mihomo GitHub Releases page and find the latest release. Under Assets, pick the right file for your machine:

• 64-bit Intel/AMD processor (the vast majority of users): mihomo-windows-amd64.zip
• ARM-based processor (Surface Pro X, Copilot+ PCs, etc.): mihomo-windows-arm64.zip

Extract the archive to get the mihomo-windows-amd64.exe executable.

Step 2: Replace the Kernel File

The kernel file location varies by client:

• Clash for Windows: Navigate to resources\static\files\win\x64\ inside the installation directory. Replace clash-win64.exe with the downloaded mihomo-windows-amd64.exe, then rename the new file to clash-win64.exe.

Step 3: Restart and Verify

Once the file is replaced, relaunch the client and check the version information in its Settings or About page. If you see "Mihomo" or "Meta" in the kernel version string, the swap was successful. You can also confirm by checking the startup log in the client's Logs panel.

macOS: Switching to a New Client

For macOS users, the recommended path is to switch directly to a modern client that ships with Mihomo built in (such as Clash Verge Rev), rather than manually swapping the kernel inside the legacy ClashX. The ClashX project itself is also abandoned, so even with a fresh kernel the GUI layer will have various compatibility problems.

Step 1: Save Your Subscription URL

In ClashX's config management panel, locate your subscription link (the https:// URL you received from your provider) and copy it somewhere safe. If you use a local YAML config file instead, back up that file directly.

Step 2: Install a New Client

Visit our download page and choose the right build for your Mac:

• Apple Silicon (M1 / M2 / M3 / M4 chips): download the ARM64 (Apple Silicon) build
• Intel Mac: download the x64 build

On first launch, macOS may show a security warning. Open System Settings → Privacy & Security and click Open Anyway to proceed.

Step 3: Import Your Subscription

In the new client's Subscriptions or Profiles section, paste the URL you saved earlier and click Import or Update. Once the node list loads, you can select a node and start browsing.

Config File Migration Notes

Mihomo is highly backward-compatible with legacy Clash Core configuration syntax, so most existing config files will load without any changes. That said, a handful of fields differ between the two, and these differences are the most common source of post-upgrade breakage:

Key Configuration Differences

Minimal Mihomo Config Example

Below is a minimal config.yaml that is fully compatible with Mihomo. Use it as a reference when migrating your existing configuration:

YAMLmixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: true

external-controller: '127.0.0.1:9090'
secret: ''

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: '198.18.0.1/16'
  nameserver:
    - 'https://doh.pub/dns-query'
    - 'https://dns.alidns.com/dns-query'
  fallback:
    - 'https://cloudflare-dns.com/dns-query'
    - 'tls://dns.google'
  fallback-filter:
    geoip: true
    geoip-code: CN

tun:
  enable: false
  stack: system
  dns-hijack:
    - 'any:53'
  auto-route: true
  auto-detect-interface: true

proxies: []

proxy-groups:
  - name: "Proxy Select"
    type: select
    proxies:
      - "Auto Select"
      - DIRECT

  - name: "Auto Select"
    type: url-test
    proxies: []
    url: 'http://www.gstatic.com/generate_204'
    interval: 300

rules:
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Select

Common Post-Upgrade Issues and Fixes

Even after following the steps above, you may run into a few snags. Here are the most frequently reported problems and how to resolve them:

Issue 1: Dashboard Not Loading (ERR_CONNECTION_REFUSED)

This is the single most common complaint after upgrading. The usual cause is that the external-controller listen address changed from 0.0.0.0:9090 to 127.0.0.1:9090, or the port is being blocked by a firewall.

Fix: Open your config file and check the external-controller value, then access the corresponding address in your browser (e.g., http://127.0.0.1:9090/ui). If you are using a GUI client, look for an "Open Dashboard" button in Settings — that is the fastest way to get there.

Issue 2: All Nodes Timing Out or Failing

There are several possible causes for this:

• Stale subscription: If your provider has upgraded their server-side protocols, the node configuration in your old subscription link may be outdated. Trigger a manual "Update Subscription" in the client to fetch the latest node list.
• DNS resolution failure: Mihomo enables fake-ip mode by default. Incorrect DNS settings can prevent node hostnames from resolving. Review your dns.nameserver entries and make sure you have at least one reliable upstream DNS configured.
• System proxy not set: The Mihomo kernel does not configure the system proxy automatically. Make sure your GUI client has system proxy enabled, or set it manually to 127.0.0.1:7890.

Issue 3: TUN Mode Fails to Start

TUN mode requires elevated privileges to create a virtual network adapter. On Windows, run the client as Administrator or enable its Service Mode. On macOS, allow the client to install its system extension under System Settings → Privacy & Security.

Issue 4: Rule Config Fails to Load

Mihomo enforces stricter rule syntax than the legacy core. The most common problems are:

• RULE-SET entries require a matching rule-providers definition. Writing RULE-SET,foo,DIRECT without defining foo as a provider will cause a parse error.
• Rule set files must be valid YAML or MRS format. Mihomo does not accept certain non-standard rule set formats that the old core tolerated.
• Proxy group names must not contain special characters. Stick to letters, numbers, and spaces.

Post-Upgrade Verification and Performance Tuning

Once the migration is complete, run through the following checks to confirm everything is working, then apply a few optional tweaks to get the best performance out of Mihomo:

Verification Checklist

1. In the Dashboard's Proxies tab, confirm the node list loads correctly. Run a latency test (Ping) on your most-used nodes and make sure valid latency values are returned.
2. Open a website that is not accessible without a proxy (e.g., Google) in your browser and confirm it loads.
3. Check the Dashboard's Logs tab for real-time output. There should be no persistent ERROR or FATAL messages.
4. If you use REALITY or Hysteria2 nodes, confirm those nodes return a valid latency reading — the legacy kernel cannot parse these node types and will always show a timeout.

Performance Optimization Tips

After migrating to Mihomo, consider these configuration adjustments to further improve your experience:

• Enable TCP concurrent connections: Add tcp-concurrent: true to your config. Mihomo will race multiple connection attempts simultaneously and use the fastest one.
• Enable geodata auto-update: Mihomo can automatically refresh GeoIP and GeoSite data files, keeping your traffic routing rules accurate and up to date.
• Persist selected proxy: Set profile.store-selected: true so that your last-selected node is remembered across client restarts — no need to manually pick a node every time.

Wrapping Up: Mihomo Is the Right Long-Term Choice

The archival of legacy Clash Core sends a clear message — the proxy ecosystem has entered a new phase centered on Mihomo. In terms of protocol breadth, ongoing security updates, and compatibility with modern configuration syntax, Mihomo outclasses the old kernel on every dimension.

If your current client still works well enough for your needs, swapping just the kernel file is a low-effort upgrade path. If the client itself is also abandoned — as is the case with the original Clash for Windows — migrating to a modern client is the cleaner solution and will save you ongoing maintenance headaches down the road.

When choosing a new client, look for one that deeply integrates the Mihomo kernel and offers a polished GUI. These clients typically invest heavily in the areas users touch most: subscription management, proxy switching, TUN mode toggle, and rule editor. They deliver a far smoother day-to-day experience compared to running the kernel directly from the command line.

If you run into any problems not covered in this guide, check out our documentation page for more in-depth configuration walkthroughs. Alternatively, give our recommended client a try — it ships with sensible defaults pre-configured and is designed to get even first-time Clash users up and running in minutes.