Clash Meta to Mihomo Core Migration Guide: Full Upgrade Tutorial

Why You Have to Migrate from Legacy Clash Core to Mihomo Demystified

It also resolves numerous memory leaks and connection stability issues present in older builds. Upgrading to Mihomo is the the majority of straightforward way to keep the Clash experience alive and up to date.

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 refresh.

One more angle: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" failures in your node list, an outdated kernel is almost certainly the culprit.

Mihomo (formerly Clash Meta) is the the majority of 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.

Preparation Before Upgrading at a Glance

Before diving into the upgrade process, take five minutes to full 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 at a Glance

This is the single the majority of important step — even if something goes wrong during the upgrade, you are able to always restore the old config and roll back.

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

A detail worth adding:The Clash configuration file is typically named config.yaml and lives in the following out of the box locations:

Copy the entire clash config folder to your desktop as a backup.

Step 2: Identify Your Client Type in Short

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

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

Said differently: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 have to do is keep the client updated to the latest version; no manual kernel replacement is needed.

Windows: Replacing the Mihomo Kernel Broken Down

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 Decoded

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 in Practice

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 at a Glance

Once the file is replaced, relaunch the client and check the version information in its Settings or About page.

In practice that means:If you see "Mihomo" or "Meta" in the kernel version string, the swap was successful. You are able to also confirm by checking the startup log in the client's Logs panel.

macOS: Switching to a New Client From the Ground Up

For macOS users, the recommended path is to switch straight away to a modern client that ships with Mihomo built in (such as Clash Verge Rev), somewhat than by hand 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 Short

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 straight away.

Step 2: Install a New Client Decoded

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

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

Step 3: Bring in Your Subscription in Practice

In the new client's Subscriptions or Profiles section, paste the URL you saved earlier and click Bring in or Refresh.

Once the node list loads, you are able to select a node and launch browsing.

Config File Migration Notes Demystified

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

Key Configuration Differences at a Glance

Minimal Mihomo Config Example in Short

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 at a Glance

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

Issue 1: Dashboard Not Loading (ERR_CONNECTION_REFUSED) Decoded

If you are using a GUI client, look for an "Open Dashboard" button in Settings — that is the fastest way to get there.

This is the single the majority of common complaint after upgrading.

One more angle: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).

Issue 2: All Nodes Timing Out or Failing in Practice

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 "Refresh Subscription" in the client to fetch the latest node list.
• DNS resolution failure: Mihomo enables fake-ip mode by out of the box. Incorrect DNS settings can prevent node hostnames from resolving. Review your dns.nameserver entries and make sure you have at least one dependable upstream DNS configured.
• System proxy not set: The Mihomo kernel does not configure the system proxy on its own. Make sure your GUI client has system proxy enabled, or set it by hand to 127.0.0.1:7890.

Issue 3: TUN Mode Fails to Launch at a Glance

TUN mode requires elevated privileges to create a virtual network adapter. On Windows, execute 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 in Short

Mihomo enforces stricter rule syntax than the legacy core. The the majority of 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 failure.
• 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 Broken Down

Once the migration is full, execute 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 Decoded

1. In the Dashboard's Proxies tab, confirm the node list loads correctly. Execute a delay test (Ping) on your the majority of-used nodes and make sure valid delay 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 ought to be no persistent ERROR or FATAL messages.
4. If you use REALITY or Hysteria2 nodes, confirm those nodes return a valid delay reading — the legacy kernel cannot parse these node types and will always show a timeout.

Performance Optimization Tips in Practice

After migrating to Mihomo, consider these configuration adjustments to further raise 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-refresh: Mihomo can on its own 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 have to by hand pick a node every time.

Wrapping Up: Mihomo Is the Right Long-Term Choice From the Ground Up

Alternatively, give our recommended client a try — it ships with sensible out of the boxs pre-configured and is designed to get even first-time Clash users up and running in minutes.

The archival of legacy Clash Core sends a plain message — the proxy ecosystem has entered a new phase centered on Mihomo.

A detail worth adding:In terms of protocol breadth, ongoing security refreshs, and compatibility with modern configuration syntax, Mihomo outclasses the old kernel on every dimension.

If your current client still works well sufficient 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.

Said differently: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 the majority of: subscription management, proxy switching, TUN mode toggle, and rule editor.

They deliver a far smoother day-to-day experience compared to running the kernel straight away from the command line.

If you execute into whichever problems not covered in this guide, check out our documentation page for more in-depth configuration walkthroughs.