· Platforms · 8 min read

Install a Clash Client on iPhone: App Store Regions and Subscription Setup

Find out how to get Clash clients for iOS, what to know about App Store regions, and how to import a profile by URL, file, or QR code before checking your first connection.

Can't Find a Client in the App Store? Check Your Region and iOS Compatibility

Open the App Store listing from the developer's official page, then check the developer name, minimum iOS version, and supported configuration formats. A Clash name in the search results doesn't tell you whether the app uses the mihomo core or can read your existing Clash YAML.

  • App Store region: If the listing says the app isn't available in your location, check the country or region linked to your current Media & Purchases account. Availability depends on the App Store storefront; changing your device language or network won't change your account's store region.
  • Minimum iOS version: Check the requirement under “Information” → “Compatibility” on the App Store listing, then check your iOS version under “Settings” → “General” → “About.” For example, if an app requires iOS 17.0 and your device is running iOS 16.7, changing your store region won't meet the requirement.
  • Subscription format: If you have a complete Clash YAML file, choose an app that explicitly supports that format. If an app only accepts its own configuration format, ask your subscription provider whether it offers a compatible option before buying. Support for importing individual node links doesn't mean the app can read a full rules-based configuration.

Apple Account Region: Check Your Purchases Account Before Changing It

To check, go to “Settings” → “your name” → “Media & Purchases” → “View Account” → “Country/Region.” Menu labels may vary by iOS version. This is the account used for purchases, not the “Language & Region” setting under “General.”

What to Check Before Changing Your Existing Account's Region

Check your account balance, subscriptions, Family Sharing status, and payment requirements in the destination region first. Apple may require you to spend your balance, cancel subscriptions that prevent a region change and wait for them to expire, or leave Family Sharing. The destination region may also require a valid payment method and billing address. Before changing regions, make sure your usual apps will still be available to download. A region change isn't a switch you can always undo immediately.

Already Have an Apple Account for Another Region?

If you already have an account for another region that meets local requirements and need it to get the app, make sure you can receive its two-factor authentication codes. If you only need to switch the account used for purchases, do so under “Media & Purchases”; don't sign out of iCloud from the bottom of your Apple Account settings. App purchases remain tied to the account used to get them, which you may need later to update or redownload the app. Avoid shared accounts, and never give anyone your password or verification codes.

Import a Clash Subscription: URL, YAML File, or QR Code?

Verify the source, then check what it contains. An HTTP or HTTPS URL might point to an updateable subscription or just a login page. A QR code might contain a subscription URL or only a single node. A full Clash configuration commonly includes top-level fields such as proxies, proxy-providers, proxy-groups, and rules, though the exact combination varies. If the configuration uses remote providers, make sure the client supports the relevant fields and can fetch their content.

  1. Subscription URL: On your provider's site, select an output format compatible with your client and copy the full URL. In the app, open “Profiles” or “Subscriptions,” choose the URL import option, and save it. Refresh the subscription once, then select the new profile for use. If an update returns 401 or 403, check whether the token has expired, the full URL was copied, and the import option is appropriate. If it returns 200 but parsing still fails, check whether the response is actually an HTML login page or another format.
  2. Local file: Save a trusted .yaml or .yml file in the Files app, then choose it from your client's file import option. If the client offers a share extension, you can also touch and hold the file in Files, tap “Share,” and send it to the app. Keep the original and edit a copy. For parsing errors, check the reported line and the one above it for indentation, colons, and list nesting. Renaming a webpage or text file with a YAML extension won't convert its contents. You usually need to import the new file again to update the local copy.
  3. QR code: Display a trusted QR code on another device, then scan it using the client's import option. To scan a screenshot on the same iPhone, the client must support importing from Photos; if it doesn't, copy the URL from the provider's site instead. If scanning adds only one node, don't assume that policy groups and rules were imported too. If the camera won't open, check permissions under “Settings” → “Privacy & Security” → “Camera.”

First Connection on iOS: Check the VPN, Active Profile, and Matched Rules

  1. Check the active profile. After importing, open the profile details and make sure the expected nodes and policy groups are there. If a policy group relies on remote providers, refresh it and check whether the fetch succeeded. Choose a node in any manually selected group so the exit node doesn't switch automatically while you troubleshoot.
  2. Allow the VPN configuration. When you start a client that uses the system VPN, iOS may ask permission to add a VPN configuration and verify your identity. Approve only a request you just initiated. You can check its status later under “Settings” → “General” → “VPN & Device Management” → “VPN.” If your device is managed by your employer or school and adding configurations is restricted, contact the administrator.
  3. Test both routes in rule mode. Send one request to a domain explicitly set to DIRECT in the configuration, then another to a domain explicitly assigned to a proxy policy group. If the client provides connection logs, note the domain, matched rule, policy group, and final route. A webpage loading or a VPN icon in the status bar alone doesn't prove that a specific request went through the proxy.
  4. Retest on another network. Test over Wi-Fi first, then switch to cellular and retry with the same node and test domain. If it fails on only one network, check whether Wi-Fi requires a captive portal login, whether cellular data is enabled for the app, and whether the failure occurs during DNS resolution or connection. Then consider changing the configuration.

VPN connections shown by iOS clients typically rely on the system's Network Extension. Even if an app supports Clash configurations, that doesn't mean desktop fields such as tun, mixed-port, or external-controller will work unchanged. Support for routing specific traffic, exposing local ports, or using custom DNS depends on the app and its core implementation.

Profile Imported but Websites Won't Load? Troubleshoot by Failure Stage

SymptomWhat to Check First
Import Succeeded, but the Policy Group Is EmptyCheck whether proxy-providers loaded successfully and whether the client supports the provider format. If you scanned a QR code for a single node, request the full configuration instead.
VPN Is Connected, but Requests Go DirectCheck whether the client is in Direct mode, or whether the request matched a direct rule first in Rule mode. Then check whether the selected node in the proxy policy group is actually DIRECT.
Direct Traffic Works, but Proxy Requests Time OutOn the same network, switch to a node you know works. If the logs show a DNS error, check DNS resolution for the node's hostname. For connection timeouts or certificate errors, check the server address and port, or the device's date and time, respectively.
Neither Direct nor Proxy Traffic Works with the VPN OnDisconnect first and make sure the underlying network works. Then check whether another VPN or DNS configuration is affecting the test. Change one thing at a time and record the results before and after; don't change the subscription, node, and DNS settings all at once.

For example, if the logs show that a test domain ultimately matched MATCH,DIRECT, the request fell through to the direct fallback. First check whether the expected rule exists, is in the right order, and whether the rule set loaded successfully. If the logs show that the request entered the expected proxy group but timed out while connecting to a node, focus on the node and network instead. This helps distinguish a routing issue from an unreachable node.

Download Clash