How to Set Up a VPN on Mac: macOSGuide

Setting up a VPN on a Mac usually means installing a compatible client, importing your subscription, granting the required permissions, choosing a route, and checking that apps connect as expected. macOS’s built-in VPN settings can’t import common proxy subscriptions directly. Pasting a subscription URL into the system’s server address field usually won’t establish a connection.

Before you install: check client and subscription compatibility

First, distinguish a system VPN from a proxy client. VPN settings in System Settings are for supported VPN protocols, while businesses may also deploy connection details through configuration profiles. Protocols such as Shadowsocks, VMess, Trojan, VLESS, Hysteria2, and TUIC require a compatible client. An app with “VPN” in its name doesn’t necessarily support every format.

Protocol names don’t mean every client supports them in the same way. Even when two clients support the same protocol, subscription formats, transport options, and rule syntax may differ. Use the macOS download instructions and import option provided in your service dashboard, and don’t convert a subscription URL to another format yourself.

1. Open About This Mac to check your chip type and macOS version. Choose an installer for Apple silicon or Intel, as appropriate. For a universal installer, check the release notes for compatibility.
2. Go to the downloads page in your account dashboard and sign in to access the client instructions and subscription. Whether a service requires payment depends on its specific features; downloading a client does not necessarily mean paying for a service.
3. Make sure the app comes from the release channel linked in your dashboard. If you’re installing from a disk image, drag the app to Applications as prompted, then launch it from there.

First launch: review macOS permissions one by one

When you open the app for the first time, macOS may ask you to confirm its source. Some clients use only the system proxy and don’t need to create a VPN configuration. TUN mode or network extensions may require permission to add a VPN configuration, install a helper, or approve an extension in System Settings. The prompts depend on how the client is built.

If you see a message such as “Apple cannot check it for malicious software,” first verify the download source and the developer’s instructions, then check Privacy & Security in System Settings. If macOS offers an option to open the app anyway, confirm its source before proceeding. If the app is reported as damaged or containing malicious software, don’t bypass the restriction with a Terminal command. Download a fresh installer and check with the publisher.

If the app requests administrator approval, confirm that the request came from the app you just launched and review what it will do. A network-routing helper is not the same as Full Disk Access; don’t grant every permission just to get online. Menu locations vary across macOS versions, so search System Settings for VPN, extensions, or network filters.

• ✅ The app is in Applications, and its download source matches the publisher’s instructions.
• ✅ Required network permissions are approved, and the client is no longer waiting for authorization.
• ✅ Other proxy clients are temporarily disabled to prevent apps from repeatedly changing system proxy settings.
• ❌ Don’t disable System Integrity Protection or grant unrelated permissions just because a guide tells you to.

Import your subscription: update it, then choose a route

Sign in to your service dashboard and find the subscription section. If there’s an import button for a specific client, make sure it matches the client you installed. To add a link manually, create a remote profile in the client’s Subscription, Configuration, or similar section, then paste the full URL. Check the client’s documentation for the exact button names.

Save the URL and update the profile. Confirm that the configuration is selected, the route list appears, and the client reports no parsing errors. A successful import only means the client received the configuration; it doesn’t confirm that a route is connected. Select a route or policy group, enable proxy mode, and visit a site you actually intend to use.

If the subscription is reported as invalid, check for extra spaces, line breaks, or a missing part at the end of the URL. If the client reports an unsupported field, check its version and the subscription format rather than deleting configuration entries at random. For network errors during an update, distinguish an unreachable subscription URL from an unavailable route: the request to fetch the configuration may not be going through the proxy yet.

Update subscriptions as instructed by your service dashboard and client. You can refresh manually after route changes; there’s no need to import repeatedly just to “stay online.” If the link has been exposed, reset the subscription credentials in your dashboard first, then import the new link on your devices. Check the dashboard to see whether the old link has been invalidated.

System proxy or TUN mode: which should you use?

If you only need a browser to access international websites, start with the client’s recommended system proxy and rules mode. Developer tools, terminal apps, and some other software may not use system proxy settings, so “the browser works, but other apps don’t” doesn’t necessarily mean the route is down.

TUN mode is sometimes called virtual network interface mode, but implementations vary between clients. It doesn’t automatically route all traffic through a remote server, nor does it replace DNS checks. If you use a company VPN, network-filtering software, or a security proxy, routing and name resolution may conflict. Follow your organization’s network policies first.

Rules mode determines which destinations connect directly and which use the proxy. Global mode generally sends more eligible requests through the proxy, but it still doesn’t capture the entire system. Avoid changing DNS, enabling global mode, and replacing rules all at once. Keep the recommended defaults, confirm the basic connection works, then adjust one setting at a time to make issues easier to trace.

Verify the connection: check your IP, DNS, and the apps you use

A “Connected” status in the client is only a starting point. First confirm your local network works with the proxy off, then turn it on and visit the site you want to use. Check the client’s connection logs to see whether the destination matched the expected rule and used the selected route. Don’t rely only on a menu bar icon or a route test.

An IP lookup can help show where a browser request is going, but it only reflects that particular request. Websites usually estimate location from IP databases, so an inaccurate location doesn’t necessarily indicate a connection problem. If the rules send the test site directly, an unchanged IP may be expected.

How to check whether DNS is handled as expected

DNS tests show clues about how a test domain was resolved; they’re not a complete privacy audit. Browser Secure DNS, the system resolver, client-side DNS handling, and routing rules can all be in play. Use the client logs, test results, and configuration documentation together to check whether destinations expected to resolve through the proxy are instead being sent to your local resolver.

If the results aren’t what you expect, check the client’s DNS mode, whether TUN mode is active, and whether the browser has encrypted DNS enabled separately. Encrypted DNS doesn’t guarantee that requests use the proxy, and a resolver’s name alone doesn’t prove there’s a leak. After making a change, test again in the same app so you’re not comparing different apps’ behavior.

Why does the browser work when the terminal doesn’t?

Terminal tools may rely on their own settings or proxy environment variables. Check the tool’s proxy documentation, then configure it with the local address, port, and proxy type shown in your client. Don’t copy a port from someone else’s guide. TUN mode is another option, but check the client’s connection logs to confirm that the process is being routed through it.

scutil --proxy
scutil --dns

These macOS commands show your current system proxy and DNS settings; they won’t establish a connection for you. The output may include internal domain names and network addresses, so redact it before sharing. An enabled system proxy also doesn’t prove that every app is using it.

Common issues: narrow down the cause based on what you see

No websites load after connecting

Turn off the client first and check whether your regular connection works. If it doesn’t, resolve any network sign-in or access issues first. If it works with the client off, confirm the configuration is up to date, select a working route in the policy group, and check the connection logs. Don’t start another client to “stack a fix”—that can create a proxy loop.

Some websites work, but a specific service still reports an error

Check which rule matched the destination, your service account status, and the platform’s access restrictions. A working route and permission to use a platform are separate issues; a successful connection to a route doesn’t mean every service will work. When switching routes, leave other settings unchanged and compare the app’s behavior to avoid changes you can’t reproduce.

Your Mac can’t connect after you quit the client

An unexpected exit may leave system proxy settings enabled. If possible, reopen the client, turn off the system proxy, and quit normally. If the problem persists, check the proxy settings for your current network connection. Remove only entries you can confirm were added by that client; don’t delete organization-managed settings on a managed device.

Disconnected after waking from sleep or switching networks

Switching networks can invalidate existing connections. First confirm that the new network works, then reconnect the client. If TUN mode or an extension isn’t working properly, disable and re-enable it as described in the client’s documentation. When reporting an issue, include the OS and client versions, connection mode, and a redacted error message; this is usually more helpful than repeatedly reinstalling. You can also consult the user guide for further troubleshooting.