For anyone setting up v2rayN on Windows or macOS for the first time. First, make sure the package and core can run. Then test a server and local proxy port. Finally, enable the system proxy and launch at sign-in. Check each step separately to tell whether the app failed to start, the port isn't listening, or an application isn't using the proxy.
First launch: choose a package, enable a server, test the proxy
This guide uses the v2rayN 7.x desktop version. Menu layouts can vary between minor releases and builds, especially the Windows tray menu and macOS interface. Before the first launch, quit other proxy clients, leave TUN off, and keep LAN access disabled.
Check your architecture
On Windows, go to Settings → System → About and check the system type to distinguish x64 from ARM64. On macOS, open the Apple menu → About This Mac and check the chip or processor: Apple silicon means ARM64, while Intel means x64. Choose a client and bundled core built for the same architecture.
Extract the package
Fully extract the Windows portable archive to a permanent folder, then run
v2rayN.exefrom there. Dragging only the main executable out of the archive leaves behind required files. On macOS, extract the archive, move the entirev2rayN.appto Applications, then launch it from there.Add a test server
If you have a single share link, copy it and use the clipboard import option in the Server menu in the main window. If you only have a subscription URL, go to Subscription Groups → Subscription Group Settings, add a group, then update the subscription. Once entries appear, select one and set it as the active server.
Check the listening port
Open Settings → Preferences and check the local listening port. Then check the main window log to confirm the core started successfully. Note the actual port and whether it accepts HTTP, SOCKS, or mixed proxy traffic. Don't confuse it with the remote port shown in the server editor.
Enable the system proxy
Choose Set system proxy automatically from the client's system proxy menu. On Windows, you can open it from the tray icon's context menu. Then visit a webpage in a browser that uses the system proxy. If the browser has its own proxy extension or settings, rule those out first.
App and core locations: permissions, paths, and architecture
Opening the main window only confirms that the v2rayN interface has started. The core process handles connections. After importing a server, make sure its selected core can be found and run. Check the startup log before considering a different package or updating the core.
Check the app location for your platform
Windows: keep the full folder intact
- You can put the portable version in a permanent folder writable by your account. Don't launch the app from the archive preview, and don't copy only
v2rayN.exe. - A common 7.x folder layout keeps the core in a
binfolder under the app directory, for examplebin\xray\xray.exe. If the file is missing, first check whether you downloaded a package that includes the core, or use the client's core update option to add it. - A missing runtime warning and a write-permission error are different issues. For the former, check the required runtime and architecture. For the latter, make sure the app or data folder is writable. Don't treat running as administrator as the default fix.
macOS: keep the app bundle intact
- Don't move or rename executables inside
v2rayN.app. Check the current release package and startup log for the core's actual location; don't assume it follows the Windows folder layout. - If the log shows
bad CPU type in executable, check whether the error refers to the client or the core, then install a package that matches your Mac's architecture. Reimporting a subscription won't change the executable's architecture. - If macOS blocks the app from opening, read the specific warning and check the download source and any device management requirements. Don't disable system protections just to launch one app.
Before moving or upgrading, quit the old instance and back up the configuration folder used by the current version. After moving the app, launch it once from its new location, then check existing shortcuts and startup items.
When backing up, don't keep only the main executable, and don't treat logs as a configuration backup. Subscription URLs may contain access tokens, and server entries may include credentials. When sharing an error report, include the error type and necessary paths, but remove subscription URLs, server credentials, and unnecessary account names from paths.
Choose a core based on the active server's protocol settings
A subscription provides a set of entries; the core interprets and runs each one. A successful subscription update doesn't mean every configuration is compatible with the selected core. In Settings → Preferences, check the core assigned to the relevant protocol. If the server editor offers a per-server core option, check whether one has been set.
Use the core that matches the server entry
RecommendedKeep the protocol and transport settings confirmed after import. For example, if an entry is explicitly configured for VLESS + REALITY, use an Xray core that supports that combination. Don't assume a connection failure is caused by the core, or change REALITY to TLS just to see if it works.
Best for: first-time setup when the server settings are clearly documented
Test an alternate core with a single entry
If the provider explicitly says a VMess configuration works with both V2Ray and Xray, keep the known-good settings and switch the core for that entry only. Compare the startup logs. Recognizing a protocol name doesn't guarantee support for the entry's transport and security options.
Best for: isolating core compatibility issues when you can reproduce the problem
Local port and system proxy: check listening and routing separately
The local listening port is for apps on the same computer; the remote port is for the core to connect to the server. They can differ. Enabling the system proxy lets apps that follow system settings find the local proxy. It won't fix the core's connection to the remote server, and it doesn't mean every app routes traffic through the proxy.
- Log reports that the port is in use: Quit another proxy client or an older v2rayN instance first. If the process using the port must stay open, assign v2rayN an unused port, restart the core, and reconfigure the system proxy. Update any apps where you manually entered the old port.
- The port is listening, but the browser still can't connect: On Windows, check Settings → Network & Internet → Proxy. On macOS, check System Settings → Network → select your current network service → Details → Proxies. Verify the system's actual settings; there's no need to enter them again manually. If an app requires an HTTP proxy, don't give it a SOCKS-only port.
- Webpages stop loading after you quit: Check whether the system is still pointing to a local port that is no longer listening. Before quitting, you can select Clear system proxy in the client. If your workplace or school configured a proxy, restore its original settings instead of turning the proxy off entirely.
Launch at sign-in: check the app path and proxy status
First confirm that you can browse the web after launching the app manually, then configure it to start at sign-in. Desktop apps usually launch after you sign in; they don't provide a proxy as soon as the device powers on, before login. Autostart only launches the app. It doesn't confirm that the core started or that the system proxy is in the required mode.
- On Windows, first look for a Start automatically with Windows option under Settings → Preferences. If your build doesn't offer one, press Win + R to open
shell:startup, then add a shortcut to the app's current location. Choose one method to avoid launching it twice. - On macOS, go to System Settings → General → Login Items & Extensions and add v2rayN from Applications to the Open at Login list. Some versions call this page Login Items. If you moved the app, make sure the list points to its new location.
- Sign out and back in. Confirm that the client launches only once, the expected server is still active, and the local listening port matches the system proxy settings. If the network isn't ready at startup, wait for it to come back and test again before deciding whether autostart failed or the connection simply took longer to establish.