Install Clash on Linux: Full mihomo Setup for Desktop Distros and CLI Environments

Pick Your Route First: GUI Client or the mihomo Kernel

The Clash ecosystem on Linux has two layers. At the bottom sits the kernel, which parses configuration and routes traffic; the actively maintained kernel today is mihomo (formerly Clash Meta). On top sit the GUI clients, which wrap the kernel in a window and provide subscription management, node switching, and a system proxy toggle. The two routes match two kinds of environments:

• Desktop distributions (Ubuntu, Debian, Fedora, and others with a graphical interface): install a GUI client. Clash Verge Rev ships deb and rpm packages, FlClash ships a deb package, and both work out of the box.
• Servers, WSL, and minimal containers (no graphical interface): deploy the mihomo kernel directly, manage it with a config file plus systemd, and pair it with a web dashboard to inspect status.

Both routes share the same YAML configuration syntax, and subscription links work across them, so switching routes later does not require rebuilding your config. Full steps for each follow below.

Desktop Distributions: Install a GUI Client

Debian / Ubuntu Family (deb Package)

After grabbing the deb package for your architecture from the download page, run in a terminal:

sudo dpkg -i clash-verge_*_amd64.deb
sudo apt-get -f install   # run only if dpkg reports dependency errors

Once installed, launch it from the application menu, paste your subscription link on the subscription page, update, pick a node, and flip the "System Proxy" switch. The client writes the system proxy for GNOME and KDE automatically, so browsers and most desktop apps start using the proxy right away.

Fedora / RHEL Family (rpm Package)

sudo dnf install ./clash-verge-*.x86_64.rpm

dnf pulls in dependencies automatically; subscription import and the toggle flow afterwards are identical to the deb route.

A few applications ignore the system proxy settings (some command-line tools and desktop apps with their own network stack). In that case, enable the client's TUN mode so the kernel takes over all TCP/UDP traffic at the system level. TUN creates a virtual network interface, so the client will ask for administrator authorization.

CLI Environments: Deploy the mihomo Kernel

Servers and WSL have no windows, so you run the kernel directly. The whole process takes four steps:

1. Get the Binary

   Grab the mihomo Linux build from the kernel section of the download page — linux-amd64 or linux-arm64 depending on architecture. After extraction you get a single executable with no other dependencies.

2. Install to a System Path

   Run sudo install -m 0755 mihomo /usr/local/bin/mihomo to place the file on a standard path with execute permission.

3. Prepare the Config Directory

   The conventional directory is /etc/mihomo, holding a config.yaml. The raw content of a subscription link cannot be used as a config directly — it must be written as the three sections proxies, proxy-groups, and rules. A more convenient approach is to reference the subscription URL with proxy-providers, and the kernel will fetch it automatically and refresh it on a schedule.

4. Test Run in the Foreground

   First run mihomo -d /etc/mihomo once in the foreground, confirm the config loads without errors and the ports are listening, then hand it over to systemd.

A minimal working config looks like this:

mixed-port: 7890
allow-lan: false
external-controller: 127.0.0.1:9090
proxy-providers:
  airport:
    type: http
    url: "https://example.com/subscribe"
    interval: 86400
    path: ./providers/airport.yaml

mixed-port accepts both HTTP and SOCKS5 requests; external-controller is the kernel's REST API, which web dashboards use to read and write runtime state — binding it to the loopback address is enough.

systemd Management and Autostart on Boot

Create the unit file /etc/systemd/system/mihomo.service:

[Unit]
Description=mihomo kernel
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Then register and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
journalctl -u mihomo -f   # follow the live log

enable --now registers autostart on boot and starts the service immediately in one command. After every config change, run sudo systemctl restart mihomo to apply it.

Permissions for TUN Mode

TUN needs to create a virtual network interface, which regular users cannot do by default. Two options: run as root directly with the unit file above, or grant the binary network administration capability and run it as a regular user:

sudo setcap 'cap_net_admin,cap_net_bind_service=+ep' /usr/local/bin/mihomo

Verify the Proxy Works

The most direct check is to send one request with proxy parameters:

curl -x http://127.0.0.1:7890 https://api.ip.sb

If the returned exit IP matches the region of the selected node, the link is working. You can also write the proxy into the shell environment so all subsequent commands use it:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

If you want a graphical interface, attach a web dashboard: place static dashboard files such as metacubexd, zashboard, or yacd into the ui subdirectory of the config directory, then visit http://127.0.0.1:9090/ui in a browser to view active connections, switch nodes, and test latency. The dashboard is only a frontend for the kernel API — closing the page does not affect the proxy.

Two Differences for WSL and Servers

WSL2

Under the default NAT network, WSL and Windows each have their own loopback address. When the proxy runs inside WSL, Windows needs allow-lan: true in the config and must connect via the WSL IP. A smoother approach is to install the client on the Windows side and export the proxy in WSL pointing at the Windows host IP — the nameserver in /etc/resolv.conf is the host address. With WSL's mirrored networking mode enabled, both sides share localhost and all these detours disappear.

Servers

Servers have no local browser, so reach the dashboard through SSH port forwarding:

ssh -L 9090:127.0.0.1:9090 user@your-server

Keep that session open, then visit the ui path on port 9090 from your local browser.

Quick Troubleshooting Reference

• Port already in use: find the process with ss -ltnp | grep 7890, or change mixed-port to another port in the config.
• Config errors: YAML only accepts space indentation, never tabs; the journalctl log reports the offending line number, so fix that line.
• Subscription not updating: the interval field of proxy-providers controls the auto-update interval in seconds; restarting the service forces an immediate fetch.
• DNS issues: enable the kernel DNS in the dns section of config.yaml with fake-ip turned on, pair it with TUN mode, or point the system DNS at the kernel's listening address.
• Rules not matching: confirm the running mode is rule rather than direct or global; the web dashboard shows the actual rule chain each connection hits.

For the full syntax of every config field, see the YAML handbook on this site; subscription import in the GUI clients is essentially the same as on Windows and macOS, with dedicated chapters in the usage documentation.