ClashX Installation Failed: 6 Common Causes & Solutions

Overview of 6 Common Installation Failures

When installing ClashX on macOS, you may encounter pop-up warnings, the app refusing to open, or the installation failing midway. Here is a quick reference for the 6 most common causes and their solutions:

Cause 1 — macOS Gatekeeper Blocks Installation

macOS Gatekeeper is Apple's built-in security mechanism that only allows apps from the App Store or identified developers by default. Since ClashX is an open-source community release without Apple notarization, Gatekeeper will block it.

Method 1: Allow via System Preferences

1. Try opening ClashX — when the block dialog appears, click OK
2. Go to System Preferences → Security & Privacy → General
3. Find the "ClashX was blocked" message at the bottom and click Open Anyway
4. Click Open in the confirmation dialog

Method 2: Remove quarantine attribute via Terminal

If Method 1 doesn't work, use the xattr command to remove the quarantine flag macOS adds to downloaded files:

sudo xattr -cr /Applications/ClashX.app

Enter your admin password when prompted, then reopen ClashX.

Method 3: Temporarily allow apps from anywhere (not recommended long-term)

sudo spctl --master-disable

This adds an "Anywhere" option in Security & Privacy. After fixing the issue, re-enable protection:

sudo spctl --master-enable

Cause 2 — Code Signing Issues

If you see "ClashX is damaged and can't be opened" or "the developer cannot be verified," the app's code signature may be missing or invalid.

Check the app's signature status

# Check Gatekeeper assessment
spctl --assess --verbose /Applications/ClashX.app

# View detailed code signing info
codesign -dv --verbose=4 /Applications/ClashX.app

# Verify signature integrity
codesign --verify --deep --strict /Applications/ClashX.app

Solutions

1. Re-sign the app (recommended): Apply an ad-hoc signature

   sudo codesign --force --deep --sign - /Applications/ClashX.app

2. Remove quarantine + re-sign:

   sudo xattr -cr /Applications/ClashX.app
   sudo codesign --force --deep --sign - /Applications/ClashX.app

3. If all else fails, re-download the latest version from the official download page

Cause 3 — Incompatible macOS Version

ClashX requires macOS 10.15 (Catalina) or later. Older macOS versions may cause installation failure or crashes on launch.

Check your current macOS version

# Check macOS version
sw_vers

# Example output:
# ProductName:        macOS
# ProductVersion:     14.3.1
# BuildVersion:       23D60

Version Compatibility

Solutions

• If your macOS is too old, upgrade macOS or use a compatible older ClashX version
• Apple Silicon (M1/M2/M3) users should ensure they download the Universal or ARM64 build

Cause 4 — Insufficient Disk Space

The ClashX installer is about 20 MB, but it needs additional space for config files and logs at runtime. Low disk space can cause the installation to abort or the app to malfunction.

Check available disk space

# Check disk usage
df -h /

# Example output:
# Filesystem     Size   Used  Avail Capacity  Mounted on
# /dev/disk1s1  460Gi  380Gi   75Gi    84%    /

Quick cleanup methods

# Clear system caches
sudo rm -rf ~/Library/Caches/*

# Clear Xcode derived data (if applicable)
rm -rf ~/Library/Developer/Xcode/DerivedData

# Clear system logs
sudo rm -rf /var/log/*.gz

# Find large files
du -sh ~/Downloads/* | sort -rh | head -20

Keep at least 5 GB of free space to ensure ClashX runs smoothly.

Cause 5 — Old Version Conflict

Installing a new version of ClashX over an existing ClashX or ClashX Pro installation may fail due to leftover configs, caches, or Helper tool conflicts.

Fully uninstall old ClashX

# 1. Quit ClashX
osascript -e 'quit app "ClashX"'

# 2. Remove the app bundle
sudo rm -rf /Applications/ClashX.app

# 3. Remove config and data
rm -rf ~/Library/Application\ Support/com.west2online.ClashX
rm -rf ~/Library/Application\ Support/ClashX

# 4. Remove preferences
rm -f ~/Library/Preferences/com.west2online.ClashX.plist
rm -f ~/Library/Preferences/com.west2online.ClashXPro.plist

# 5. Clear caches
rm -rf ~/Library/Caches/com.west2online.ClashX

# 6. Remove Helper tools
sudo rm -f /Library/PrivilegedHelperTools/com.west2online.ClashX.ProxyConfigHelper
sudo rm -f /Library/LaunchDaemons/com.west2online.ClashX.ProxyConfigHelper.plist

Verify cleanup is complete

# Confirm no leftover processes
ps aux | grep -i clash

# Confirm Helper has been removed
ls -la /Library/PrivilegedHelperTools/ | grep -i clash

After cleanup, re-download the latest version from the download page and install.

Cause 6 — Corrupted Download

If the network is unstable during download (especially when using a proxy or CDN), the installer file may be incomplete or corrupted.

Verify download file integrity

# Verify with SHA-256
shasum -a 256 ~/Downloads/ClashX.dmg

# Compare the output hash with the value on the official release page
# If they don't match, the file is corrupted and needs re-downloading

Solutions

1. Switch network: Try disabling your proxy and downloading with a direct connection
2. Use a browser: Avoid download managers that may modify the file
3. Download via curl:

   # Download from GitHub Release via curl
   curl -L -o ~/Downloads/ClashX.dmg \
     https://github.com/ClashX-Pro/ClashX/releases/latest/download/ClashX.dmg
   
   # Verify after download
   shasum -a 256 ~/Downloads/ClashX.dmg

4. Use a GitHub mirror: If direct GitHub access is slow, try a CDN-accelerated link

Frequently Asked Questions (FAQ)

Q: Are the fixes the same for ClashX and ClashX Pro?

A: Yes, essentially. Both use the same Helper tool and system permission mechanisms. All methods in this guide apply to both ClashX and ClashX Pro.

Q: Does ClashX need Rosetta on M1/M2/M3 Macs?

A: The latest ClashX natively supports Apple Silicon — no Rosetta needed. If you're using an older version, install Rosetta for compatibility:

softwareupdate --install-rosetta --agree-to-license

Q: What if I get "Operation not permitted" when running sudo?

A: This is usually related to macOS SIP (System Integrity Protection). The xattr and codesign commands normally don't require disabling SIP. If you still encounter issues, check that Terminal has "Full Disk Access" (System Preferences → Security & Privacy → Privacy → Full Disk Access).

Q: ClashX installed successfully but won't launch?

A: See our ClashX Connection Timeout Troubleshooting Guide for detailed steps on startup failures and connectivity issues.

Q: I've tried everything and still can't install. What else can I do?

A: Try the following in order:

1. Restart your Mac and try again
2. Create a new admin account and test the installation there
3. Try installing in macOS Safe Mode
4. Search or file an issue on GitHub Issues