Install Clash on Linux: Desktop App & mihomo CLI Setup Guide

Two Ways to Run Clash on Linux: Which One Fits You

There's no single official Clash desktop app for Linux, and the two viable paths are fundamentally different — picking the wrong one wastes time. The first is the desktop GUI route: install a client with a graphical interface, click around to switch nodes and import subscriptions much like the Clash clients on Windows/macOS, suited to everyday browsing on a desktop environment (GNOME, KDE, etc.). The second is the CLI core route: install only mihomo (the continuation of the Clash Meta core), a single executable that runs in the background via a config file and a systemd service, suited to cloud VPS instances, NAS boxes, and Raspberry Pi setups that lack a GUI and need to run 24/7.

Both paths share the same underlying core (desktop clients also run on mihomo/Clash Meta under the hood) — the only difference is whether you need a clickable window. Here's the simple rule:

• If you're running a Linux distro with a desktop environment (Ubuntu, Fedora, Debian, etc.) on your own laptop or desktop and want to switch nodes and check status regularly — go with the desktop client route.
• If you're managing a cloud VPS, a home NAS, or just want the proxy service to run quietly in the background with no GUI involved — go with the mihomo + systemd route.

Both routes are covered below in full, independently of each other — feel free to skip to whichever one applies to you.

Desktop Environment: Install Clash Verge Rev in Three Steps

Clash Verge Rev is currently the most actively maintained, full-featured open-source client for Linux desktops. It runs on the mihomo core, supports TUN mode for system-wide traffic takeover, and its deb package works directly on Debian/Ubuntu-based distros. Here's the complete process.

Step 1: Download the deb Package for Your Architecture

Check your system architecture before downloading — most desktops and laptops are amd64, while some ARM devices (like certain ARM laptops) need the arm64 package. Check your architecture from the command line:

uname -m
# x86_64 maps to the amd64 package
# aarch64 maps to the arm64 package

Once you've confirmed the architecture, grab the matching deb installer link from this site's download page.

Step 2: Install the deb Package

After downloading, install it with apt or dpkg — apt is recommended since it resolves dependencies automatically:

cd ~/Downloads
sudo apt install ./clash-verge-rev_amd64.deb

If the system reports missing dependencies (common on a bare-bones Debian install), run this first:

sudo apt --fix-broken install

Then reinstall the package. Once installed, the app appears in your app menu, and you can also launch it directly by typing the client's name in a terminal.

Step 3: Import Your Subscription and Enable System Proxy

After opening the client, follow these steps in order:

1. Go to the "Profiles" tab, paste the subscription link from your proxy provider, click download, and wait for the node list to load.
2. Switch to the "Proxies" tab and pick a node group with low latency, or just use the auto-speedtest policy group.
3. In "Settings", toggle on the system proxy switch, or enable TUN mode if needed (this requires entering your password for authorization; TUN takes over system-wide traffic, including apps that don't support proxy settings).

Servers & Headless Environments: mihomo Core + systemd

On machines without a GUI (cloud VPS instances, NAS boxes, router-level devices), you don't need the full client — just install the single mihomo binary, set up a YAML config, and let systemd manage its lifecycle. This route gives you lower resource usage, automatic restart on disconnect, and startup on boot.

Step 1: Download and Place the mihomo Binary

After confirming your architecture, grab the matching archive from the project's release page. Extract it to get a single executable, then rename and move it into your system path:

tar -zxvf mihomo-linux-amd64.tar.gz
sudo mv mihomo-linux-amd64 /usr/local/bin/mihomo
sudo chmod +x /usr/local/bin/mihomo

Verify it's executable:

mihomo -v

If you see the version number printed, the binary is set up correctly.

Step 2: Set Up the Config Directory and Subscription File

mihomo reads from /etc/mihomo/config.yaml by default, so create the directory first:

sudo mkdir -p /etc/mihomo
sudo curl -o /etc/mihomo/config.yaml "your-subscription-link"

If the subscription link isn't already in standard Clash YAML format (some providers issue a generic Base64-encoded format instead), generate a Clash-format link first using a client that supports conversion, then download it with the command above — otherwise mihomo will fail to parse it.

Step 3: Test Run Manually

Before wiring it into systemd, run it in the foreground once to make sure the config file is valid:

mihomo -d /etc/mihomo

Watch the terminal output — if you see a listening port (default mixed port 7890) and logs confirming the proxy groups loaded successfully, press Ctrl+C to stop and move to the next step. If you get an error, it's usually a config formatting issue or an expired subscription — double-check the YAML indentation and whether the subscription is still valid.

Step 4: Write the systemd Service Unit

Create the service file:

sudo nano /etc/systemd/system/mihomo.service

Add the following content:

[Unit]
Description=mihomo Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

Save and exit, then reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl start mihomo
sudo systemctl status mihomo

If status shows active (running), the service is up and working.

Two Ways to Import Subscriptions and Update Rules

No matter which route you take, subscription content will eventually expire or need refreshing based on your provider's rules. Here's how to update it in each environment.

Managing Subscriptions in the Desktop Client

Clash Verge Rev lets you set an auto-update interval for each subscription — click edit on the profile entry and enter an update cycle in hours; the client will re-fetch the subscription automatically on that schedule with no manual work needed. You can also click the refresh button on a profile entry anytime to update it manually.

Refreshing Subscriptions on the Command Line

mihomo has no GUI, so updating the subscription essentially means re-downloading the config file to overwrite the old one, then restarting the service for it to take effect. Here's a simple update script:

#!/bin/bash
curl -o /etc/mihomo/config.yaml "your-subscription-link"
systemctl restart mihomo

Save this script as update-sub.sh, then add a scheduled task with crontab -e to enable unattended periodic refreshing — for example, running it every day at 4 AM:

0 4 * * * /bin/bash /root/update-sub.sh

Startup on Boot and Common Troubleshooting

The two routes configure autostart differently — here's how each one works.

Autostart for the Desktop Client

Clash Verge Rev usually has a "Launch at Startup" toggle in Settings — turn it on and the client will launch automatically when you log into your desktop environment. If your distro's desktop environment doesn't pick this up correctly (some less common window managers miss autostart entries), you can manually add the client's executable path to your system's startup application manager as a backup.

Autostart for the mihomo Service

For services managed by systemd, a single enable command sets it to launch automatically on boot — no extra configuration needed:

sudo systemctl enable mihomo

Reboot the server afterward to verify: run systemctl status mihomo after the reboot, and if the status shows active, autostart is configured correctly.

Once you've got both the GUI and CLI routes figured out, you can follow the same logic going forward — whether switching nodes on your own machine or setting up a proxy exit on a server that runs around the clock: confirm the architecture and dependencies first, import the subscription, then finish by enabling autostart. If something goes wrong, just back up a step and redo it.