1 Why a dedicated migration guide matters
Clash Verge Rev is more than a tray icon that toggles system proxy. Under the hood it orchestrates the Mihomo core, keeps one or more Profiles in sync with remote subscription endpoints, merges local enhancements, and caches rule providers plus GeoIP-style databases so your YAML stays fast to evaluate. When you reinstall the operating system or buy new hardware, all of that state lives outside the installer. If you only remember the subscription URL in your head—or assume the app “syncs to the cloud” like a consumer VPN—you are one formatted disk away from a long evening of reconstruction.
The user intent behind this article is practical: you want continuity. You expect the same proxy groups, the same DOMAIN-SUFFIX lines you added for work SaaS, the same FakeIP or DoH choices, and the same mixin overlays that survive subscription refresh. Official documentation and release notes occasionally remind readers that configuration paths changed between major versions; that is exactly why you should anchor every step to Settings → App Directory inside the client rather than trusting a blog comment from three years ago. The paths below match current community reports and upstream issue logs for recent builds, yet your local “App Directory” panel remains the authoritative string for your machine.
Legally and ethically, you remain responsible for how you use proxy software. Backing up configuration does not change that obligation: store archives on encrypted volumes, avoid sharing folders that contain live subscription tokens, and rotate compromised URLs if a backup ever leaks. The workflow here is about operational hygiene for power users who already maintain legitimate access credentials.
2 What “full” means for Clash Verge Rev
Think in layers. At the top sits the GUI’s own preferences—tray behavior, update channel, language, and pointers to which Profile is active. Those typically serialize into small YAML or JSON files in the application data root. Beneath that, the profiles directory (name may appear as Profiles on case-insensitive disks) stores per-profile sources: remote subscription snapshots, locally authored files, and metadata that tells Verge how to refresh each entry. Mihomo then consumes a generated runtime configuration that merges provider content with your overrides.
Custom routing logic often arrives through mixin files or subscription Override features in the GUI—patterns we unpack in depth in the dedicated mixin and subscription override tutorial. For migration purposes, you must copy not only the downloaded provider YAML but also any merge fragments, script hooks, or append-only rule sections that the GUI keeps alongside the profile store. Missing those files produces the classic symptom: “the subscription updated and my personal rules vanished,” except in your case the rules did not vanish—they never made it onto the new disk.
Finally, optional caches matter for convenience rather than correctness. Rule-provider binaries, GeoIP databases, and similar artifacts can be re-downloaded, but hauling them across saves bandwidth on metered connections and avoids hammering public CDNs during first boot on a fresh OS. If your archive grows large, compress it; if you are privacy sensitive, omit caches and let the client refetch after restore.
3 Always confirm Settings → App Directory first
Before you copy a single folder, open Clash Verge Rev on the source machine, navigate to settings, and locate the App Directory (wording may read “Open app directory” or similar). Click through to the folder in Explorer or Finder. That path is the root of truth for your install, independent of whether you are on a stable release, a nightly, or a portable extraction. Upstream FAQ entries explicitly recommend this step because directory layouts shifted in older transitions; treating the UI-reported path as canonical prevents you from backing up an abandoned location after an upgrade.
4 Typical Windows layout
On Windows 10 and Windows 11, Roaming application data is the usual home for Clash Verge Rev. Community logs and GitHub issues consistently reference a directory shaped like %APPDATA%\io.github.clash-verge-rev.clash-verge-rev, which expands to C:\Users\<You>\AppData\Roaming\io.github.clash-verge-rev.clash-verge-rev for standard accounts. Inside, expect a profiles subtree with YAML snapshots, possibly alongside files such as verge.yaml for client-level options, verification helpers, and runtime artifacts the core writes during validation.
Do not confuse Roaming with LocalAppData unless you know your enterprise folder redirection policy. For most personal PCs, Roaming is correct. If you previously symlinked the entire directory to another drive—a common trick when C: is tight—your backup must follow the symlink target, not an empty junction. PowerShell’s Get-Item resolves link targets quickly if you are unsure.
When you are preparing a migration, close Clash Verge Rev completely, including the tray icon, so files are not locked while you zip the tree. Windows may still hold handles briefly; retry the archive after a few seconds if you see “file in use” errors. For a clean image restore scenario, boot from recovery media, mount the old volume read-only, and copy the same path from the previous Windows profile.
5 Typical macOS layout
On macOS, application support under the user library is the parallel location. Paths reported in upstream discussions follow ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/. Spaces matter when you quote them in Terminal commands, and case sensitivity on Apple-formatted volumes is usually insensitive but not guaranteed on exotic external disks—prefer quoting paths verbatim.
Before copying, quit Clash Verge Rev from the menu bar. macOS may leave helper processes alive if you only close the window; use “Quit” from the tray or run Activity Monitor if the archive tool complains. Time Machine users already have a versioned backup of Application Support; for manual migration, drag the entire io.github.clash-verge-rev.clash-verge-rev folder into an encrypted sparse bundle or a password-protected zip on external storage.
If you are coming from an Intel Mac to Apple Silicon, the architecture changes but the configuration format does not. Your YAML, mixin snippets, and profile list remain valid; only reinstall the arm64 build of the client, restore the directory, and reauthorize any TUN or system extension prompts that macOS presents on first launch. Fresh install steps are summarized in our macOS installation guide if you need a baseline before layering migration on top.
6 Cold backup workflow both platforms share
- Upgrade Clash Verge Rev on the source machine to the same major line you plan to run on the destination, when possible. Mixed very-old → very-new jumps sometimes require one intermediate launch to rewrite metadata.
- Export a human-readable list of subscription URLs into a password manager as a secondary backup, even though you are copying files. URLs are small secrets; redundancy saves you if only part of the archive restores.
- Quit the client, wait for processes to exit, then copy the entire App Directory root—not just
profiles—into a dated archive such asverge-backup-2026-04-12.zip. - Store the archive offline or in encrypted cloud storage. Do not attach it to public tickets or chat logs.
- Document oddities: custom script paths, absolute paths to certificates, or SSH keys copied into the app directory (some advanced configs do this). Those break on restore if the destination user name differs.
Windows users who have never opened %APPDATA% can paste that token into the Run dialog or File Explorer’s address bar to jump straight to Roaming. macOS users can use Finder’s “Go → Go to Folder…” menu with ~/Library/Application Support/. In both cases, prefer GUI navigation first; Terminal mastery is optional.
7 Restore sequence on the new system
Install Clash Verge Rev from a trustworthy channel before you restore data. Our downloads page lists curated entry points per platform while keeping language-specific landing pages consistent; use it when you want parity across devices. Launch the app once so it initializes its directory skeleton, then quit again. Delete or rename the freshly created io.github.clash-verge-rev.clash-verge-rev folder if it is mostly empty, and replace it with your archived copy. Alternatively, merge selectively—advanced users sometimes import only profiles plus verge.yaml—but wholesale replacement is simpler when the source machine was healthy.
Start the client, select the intended active Profile, and trigger a manual subscription update to confirm outbound HTTPS from the new OS can reach your providers. If refresh fails, fix DNS or system time first; do not assume the backup is corrupt until basic connectivity checks pass. Windows migrations often need service mode or elevation reinstalled even when files copied cleanly; macOS may prompt for new permissions for virtual interfaces. Our TUN mode guide remains the best follow-up when you need packet-level routing again after the move.
verge.yaml enabled external-controller access without authentication, recreate a secret on the new machine before joining untrusted networks. Migration duplicates old risk as well as old convenience.
8 Moving between Windows and macOS
YAML itself is portable; absolute paths are not. A rule that points to C:\Users\alice\certs\corp.pem will not resolve on macOS, and vice versa for POSIX paths misquoted on Windows. After copying Profiles, search inside the restored files for drive letters or home-directory assumptions. Replace them with neutral layouts—store certificates inside the App Directory subtree using relative references where the core allows, or re-import via the GUI.
Line endings rarely break Mihomo, yet editors sometimes rewrite files; if you observe parser errors, normalize to UTF-8 without BOM. PROCESS-NAME rules differ semantically across operating systems; expect to revisit process-based policies when jumping platforms. For Windows-specific setup context before you adapt paths, see the Windows installation tutorial.
9 Where mixin and “custom rules” actually persist
Users say “custom rules” to mean three different things: hand-edited YAML inside a profile, GUI-managed append lists that survive refresh, and global mixin fragments that merge into every generation pass. Clash Verge Rev surfaces these concepts in distinct panes, but on disk they still reduce to files the merger reads. If you back up only the remote subscription body, you will lose GUI-managed overlays that live outside the provider’s hosted YAML.
When in doubt, archive the entire application data directory. If size is a concern, include at minimum profiles, any *.yaml siblings at the root of that directory that you recognize as yours, and hidden folders your tools reveal. After restore, open the mixin editor and confirm snippets loaded; trigger a subscription refresh and verify appended rules still appear beneath provider content. That single refresh test catches most partial-copy mistakes within minutes instead of days later during travel.
10 Verification checklist after restore
- Profile selection: Confirm the intended Profile is active and nodes render in the Proxies panel.
- Latency tests: Run built-in checks knowing ICMP does not equal HTTPS throughput; spot-check a browser and one CLI tool if you rely on TUN.
- DNS path: If you used FakeIP or custom DoH, revisit resolver settings—new OS installs reset stub resolvers or enterprise policies.
- System proxy vs TUN: Reapply the mode you actually use; Windows may clear manual proxy during feature updates, and macOS may revoke prior approvals.
- Rule providers: Watch the log for 404s on rule-set URLs; rotate dead endpoints before blaming the migration.
Keep a short written changelog of what you customized across machines. Future migrations become copy-and-verify exercises instead of archaeology. Compared with ad hoc screenshots scattered across albums, a dated zip plus a three-line README in your private notes is dramatically easier to audit under stress.
11 Troubleshooting quick hits
- Blank Proxies panel after restore: Often a failed subscription fetch or a profile UID mismatch; re-import the URL once, then compare file timestamps inside
profiles. - Kernel refuses to start: Delete temporary validation files if a partial write occurred during copy, then restart; confirm no second Verge instance is locking logs.
- Rules “half” apply: Indicates incomplete mixin copy or ordering drift—open the merge preview if your build offers it, and re-append overrides.
- High disk use: Old rule-provider caches duplicated across backups; it is safe to trim caches if you are comfortable waiting for regen.
Upstream source code and issue trackers remain useful for edge cases—search there when your version string does not match community write-ups—but treat GitHub as transparency and engineering detail, not as the primary installer channel. For day-to-day installs, keep using the site download flow referenced above.
12 Wrap-up
Migrating Clash Verge Rev is fundamentally a filesystem task: capture the application data root reported in settings, compress it while the app is closed, reinstall the client on the destination, swap directories, then validate subscriptions and mixin overlays with a deliberate refresh pass. Whether you live on Windows or macOS, the same mental model applies—Profiles plus local enhancements, not just the installer binary, carry your network policy forward.
Compared with reassembling rules from memory after a disk failure, this workflow is dramatically faster and less error prone. Compared with trusting a single cloud sync folder without understanding which files are authoritative, it is also more predictable: you always know which directory to diff when something drifts. Stability ultimately comes from maintained clients and disciplined backups, not from hoping the OS upgrade preserved an opaque cache you never inspected.
Once you have walked through the steps once, keep a recurring calendar reminder to refresh your archive after major rule changes. The incremental cost is minutes; the payoff is confidence the next time hardware fails or baggage handlers misplace a laptop.
