Check your operating system and CPU first. Use a graphical client on desktop and mobile; see the mihomo core section for servers and routers.
After installing a client, import your own subscription or local configuration.
Run only one proxy client on a device at a time. Install it, import a profile, and verify the connection before considering TUN mode. Platform tabs can be shared; reopening the link returns to the selected platform.
The graphical clients below provide x64 installers. Check your system type under Settings → System → About. On ARM devices, first confirm app compatibility; an x64 client is not the same as an ARM64 core.
Windows · x64 installer
A good starting point if you want to import a profile and get connected. Run the installer, open the client, add and select a subscription on the profile page, then enable the system proxy. Keep the default port for your first connection and avoid running another proxy app at the same time. Save a working copy of your profile before changing rules.
Windows · x64 installer
For users who want to manage subscriptions, rules, and network routing settings. After importing a subscription, confirm the profile is enabled, then choose a policy on the proxy page. To use TUN, install the service and grant permission when prompted. Don't just toggle it on and close the window; confirm that both the core and service have started successfully.
Windows · AMD64 installer
For users who want a similar workflow across desktop and mobile. AMD64 refers here to the common 64-bit x86 architecture and also covers compatible Intel processors. After installing, add a profile, select a node, and connect. When migrating from another client, check separately whether your custom rules were imported with the subscription.
Windows · x64 installer
An alternative desktop interface for organizing subscriptions and proxy policies. Settings directories and interface options aren't interchangeable between clients. Migrate by importing a subscription URL or an exported profile. If the port is already in use on first launch, quit the old client and check the connection log for details.
Windows · Legacy archive
Kept for recreating legacy environments and migrating configurations. For a new install, choose a maintained client listed above. Older cores may not recognize newer protocols or configuration fields. Before migrating, note your rules, policy group names, and ports, then test each one in the new client. Don't copy the old app directory over the new one.
| Check | What to check |
|---|---|
| System type | Graphical installers are x64. Check your device architecture in System Information. Refer to the selected client's release notes for its minimum Windows version. |
| Installation permissions | Writing to the install directory, helper services, and TUN may require administrator approval. Confirm that any prompt is from the installer you're running. |
| After installation | Import and select a subscription, then test your browser with the system proxy. If a UWP app won't connect, check its loopback restrictions. |
If a UWP app can't connect, you don't need to keep reinstalling the client. First check whether the browser works and whether the app is subject to loopback restrictions. Then see Frequently Asked Questions for app-specific network restrictions.
Open Apple menu → About This Mac. If you see an Apple M-series chip, choose Apple Silicon; if you see an Intel processor, choose Intel. Open the downloaded DMG, drag the app to Applications, then launch it from the Applications folder.
macOS · DMG disk images
Choose the package for your chip, drag the app to Applications, and launch it from there rather than from the mounted disk image. Add a subscription on first launch, wait for it to finish loading, and select it. Test your browser with the system proxy first; configure login launch or TUN only if needed. Grant helper service permissions when prompted by the client.
macOS · x64 files in current list
For desktop users who want to manage profiles, rules, and service status in one place. The Apple Silicon option currently returns an Intel package, so it shouldn't be treated as a native build. After dragging the app into Applications, check that the profile loads and the proxy is enabled. Before using TUN, confirm the service installed successfully; don't mistake a failed permission prompt for an invalid subscription.
macOS · AMD64 file in current list
Offers a similar configuration workflow to the mobile app. The current download is labeled AMD64, the 64-bit x86 architecture, not Apple's ARM architecture. Before upgrading, quit the old process, replace the app in Applications, and reopen it. If the subscription updates but your browser can't connect, check whether the system proxy points to the current client's port.
macOS · Legacy archive
For recreating legacy configurations and migration reference. Both options currently point to an x86_64 disk image. Compatibility with newer systems, protocols, and configuration fields needs to be checked separately. Before migrating, keep the original YAML and custom rules; don't rely on copying menu bar options alone. For new installs, choose a maintained client above.
| Check | What to check |
|---|---|
| Chip architecture | Apple M-series chips use arm64; Intel uses x64, AMD64, or x86_64. Make sure the download filename matches your needs. |
| Operating system version | Check your macOS version in About This Mac, then compare it with the client's current release notes. Minimum requirements vary by client. |
| Install location | Drag the app to Applications, quit any app running from the disk image, then launch it from Applications. |
| Helper services | Features such as TUN may require authorization. Keep macOS security protections enabled and follow verifiable prompts from the app; don't disable security settings across the board. |
If an upgrade says the app is still running, quit the client from the menu bar and make sure its background services have stopped before replacing it. See the macOS installation section for details.
Most recent phones use ARM64. Older devices may need ARMv7. If you're unsure, check your system information or choose a client that offers a universal package. On the first connection, Android will ask for VPN permission; this system feature lets the client handle network traffic.
Android · ARM64 APK
A straightforward first install for ARM64 phones. When you open the APK, allow installation from the current download source if Android asks. After installation, add a subscription in the client and connect. Check the VPN permission and selected node first. If the connection drops when the screen locks, review the app's background and battery optimization settings.
Android · ARM and universal packages
Offers packages for multiple architectures, suited to users who want to choose a specific device build. Import and enable a profile, then start the service. The universal package supports more architectures but still has system requirements; it doesn't necessarily work with every older Android version. After changing profiles, confirm that the proxy group still selects a working node.
Android · ARM64 / ARMv7
For users who want a similar experience on desktop and mobile. Choose the build that matches your phone's app environment, then import the profile again after installation; don't copy the desktop settings directory. Android typically allows only one active VPN service at a time. Stop any other network tool before connecting with this client.
Android · Universal APK
An alternative client with a different configuration format. After installing, import a profile supported by Surfboard. Clash YAML isn't automatically compatible; check with your provider for a version in the right format. If import fails, check the format before assuming the link is broken. Convert formats carefully to preserve rules and policy groups.
| Check | What to check |
|---|---|
| Device architecture | ARM64 corresponds to arm64-v8a; ARMv7 corresponds to armeabi-v7a. Choose based on your device information, and check the client's documentation for its minimum Android version. |
| Install permission | Allow installs only from the browser or file manager you're using. You can revoke that permission after installation if you wish. |
| Connection permission | Approve Android's VPN request on first connection. Avoid running another VPN app at the same time. |
| Background operation | Test the connection with the screen on, then with it locked. Adjust background or battery settings for this app only if the connection actually drops. |
Open the app's App Store page and check the system requirements under Compatibility before installing. When connecting for the first time, add a VPN configuration when prompted. Installing the app, adding a subscription, and authorizing the connection are three separate steps; complete them in order.
iOS · App Store
After installing, open the profile page and import a compatible subscription from your service provider, then select a profile and node. iOS will ask to add a VPN configuration the first time you connect; approve it and return to the app to check the connection status. If you have other network tools installed, stop their connections before testing to avoid confusion from repeatedly switching between them.
| Check | What to check |
|---|---|
| System compatibility | Check the minimum OS version and device compatibility shown on the App Store page. |
| Subscription profile | Make sure you're importing content supported by the app, not your provider's login or account management page. |
| Connection permission | Add the VPN configuration when prompted, then check the current policy and node in the app after connecting. |
For your first test, use a website you know and check the app's connection log. A working browser doesn't necessarily mean all traffic is going through the proxy; check the active rules and policies, since direct connections are expected for some traffic in rule mode.
First check your distribution's package format. Debian and Ubuntu-based systems typically use DEB; Fedora-based systems typically use RPM. The desktop packages below are all AMD64. For headless systems, other architectures, or routers, see the core section instead of trying to install a graphical package.
Linux · AMD64 desktop client
For users with a desktop environment who want graphical profile management. Install with your distribution's package manager; if dependencies are missing, follow its instructions rather than removing packages. Launch the app from the application menu and import a subscription. Check separately whether your terminal tools use the desktop system proxy; a toggle alone doesn't confirm that they do.
Linux · AMD64 DEB
For desktop users on DEB-based distributions who want a familiar workflow across devices. Quit other clients before installation to avoid proxy port conflicts. Remote servers usually don't have a graphical session, so don't follow the desktop setup steps there. For a persistent service, deploy mihomo separately and configure service management and log access.
| Check | What to check |
|---|---|
| CPU architecture | Run uname -m to check. The x86_64 architecture matches the AMD64 desktop packages below. |
| Distribution package format | Use the package manager for DEB or RPM; don't just change a file extension and install it. |
| Desktop dependencies | Graphical clients need a desktop environment. Check your package manager and the client's release notes for specific library requirements. |
| Service permissions | TUN and route changes require appropriate permissions. Confirm which user runs the service before enabling network routing. |
If the system proxy is on but terminal traffic still isn't routed through it, check whether the tool reads desktop proxy settings or proxy environment variables. For a persistent service, see the Linux installation section and handle the configuration path, runtime permissions, and startup behavior separately.
For servers, routers, and users who manage services themselves. The core loads configuration, matches rules, and forwards traffic; it doesn't include a graphical interface. Desktop and mobile users should choose a graphical client above and don't need to download the core separately.
| System | Architecture / format | For | Download |
|---|---|---|---|
| Windows | AMD64 · ZIP | 64-bit x86 command-line environments | Download AMD64 ZIP |
| Windows | ARM64 · ZIP | Windows ARM devices | Download ARM64 ZIP |
| macOS | Intel · GZ | Intel Mac command-line environments | Download Intel GZ |
| macOS | Apple Silicon · GZ | Apple M-series Macs | Download Apple Silicon GZ |
| Linux | AMD64 · DEB | Compatible Debian-based package management environments | Download AMD64 DEB |
| Linux | AMD64 · GZ | x86_64 servers and command-line environments | Download AMD64 GZ |
| Linux | ARM64 · GZ | 64-bit ARM servers or devices | Download ARM64 GZ |
| Linux | ARMv7 · GZ | Compatible 32-bit ARM environments | Download ARMv7 GZ |
| Linux | MIPS softfloat · GZ | Compatible MIPS router environments with software floating point | Download MIPS GZ |
| Check | Requirement |
|---|---|
| Executable file | Extract ZIP archives and decompress GZ files to get the binary. On Unix-like systems, grant execute permission for the actual file path. |
| Configuration directory | Prepare a compatible YAML configuration and make sure the runtime user can read it and write to the required data directory. |
| Network exposure | Set explicit listen addresses and firewall rules. Don't expose proxy ports or management interfaces directly to the public internet. |
| Persistent operation | Start it in the foreground first and check for errors, then run it through a service manager. Keep startup logs and confirm routes recover after stopping the service. |
Check configuration syntax with mihomo -t -f config.yaml. Run the command in an environment where the core executable is available. Passing the check only means the configuration can be parsed; it doesn't confirm that nodes, DNS, or routing work. Test each separately.
Installing the app doesn't establish a connection. Follow these steps in order to pinpoint problems without reinstalling from scratch.
On Windows, run the installer; on Mac, drag the app to Applications; on Android, open the APK; on Linux, use the package manager for your distribution. Quit any old client before installing, then check that the app opens. If the system reports incompatibility, verify the architecture and OS version rather than trying several mismatched packages.
A subscription is a configuration source provided by your service provider, not a client download link. Copy its URL, add it on the profile page, and refresh it; then select the profile. Local YAML files must also be imported and enabled. Subscriptions may contain account information, so don't share full URLs or credentials from a configuration when asking for help.
Select a working node, then test your browser in rule mode with the system proxy enabled. Rule mode chooses direct or proxied connections based on conditions; global mode sends matching traffic through the selected policy. If a particular app can't connect, check connection logs and rule matches before enabling TUN. Don't use extra toggles to hide the original problem.
For step-by-step instructions, see the subscription import guide. For platform differences, service deployment, and troubleshooting, read the installation guide.
Check the installer, architecture, and profile first, then troubleshoot the connection. These answers also apply when preparing to switch clients.
Start with Clash Plus on Windows, macOS, Android, or iOS, and Clash Verge Rev on Linux. Use one client to import a subscription and verify the connection before trying another interface. Download the mihomo core separately only for servers or routers.
Open About This Mac from the Apple menu. If it lists an Apple M-series chip, choose arm64; if it lists an Intel processor, choose x64 or x86_64. Some clients in this download list link to the same x64 file from both architecture options, so check the filename before downloading. Apple Silicon may need Rosetta to run Intel apps.
The installer includes the client, not a subscription service. Open the profile page and import a valid subscription or compatible local YAML file. Select the profile and an available node, then enable the system proxy or the network-routing mode you need. Check the profile, node, and proxy toggle in that order; avoid changing multiple settings at once.
To upgrade the same client, export your profile and note any custom rules first. Quit the app and background services, then follow the release-specific upgrade instructions. When switching clients, don't overwrite the existing configuration directory. After upgrading, check the profile, proxy port, and helper service; remove old files only after confirming everything works.
For your first setup, enable the system proxy and check that your browser follows the rules. Consider TUN only if terminals, games, or other apps ignore the system proxy. TUN routes traffic through a virtual network interface and often requires a helper service or administrator privileges. After switching modes, check DNS and network connectivity again.
Both clients are discontinued. Their download links are retained for recreating legacy environments and planning migrations. For a new install, choose a maintained client. Older versions may not support newer configuration fields or protocols. Keep a copy of the original profile and test rules and subscription compatibility one item at a time when migrating.
For subscription update failures, UWP loopback restrictions, or port conflicts, see Frequently Asked Questions. An installer installs the app; contact the relevant service provider about subscription content and node availability.