v2rayN First-Time Setup: Windows and macOS Installation Guide

At a glance

For anyone setting up v2rayN on Windows or macOS for the first time. Check the download, file locations, subscription import, listening ports, and system proxy one by one. First establish a connection you can verify, then adjust routing and startup options. Ports shown here are examples and are labeled as such; rely on your current client settings and startup logs.

Choose the right download: check your OS and processor

v2rayN is a desktop client: its interface manages configurations, while the core handles connections. Opening the main window only confirms that the interface is running; it doesn't mean the core, server, or system proxy is ready. Start by choosing the right platform on the client download page, then check the processor architecture and package details.

On Windows, check System type under Settings → System → About. On macOS, check the chip in the Apple menu → About This Mac. Most Intel- and AMD-based desktop computers use x64; choose the matching architecture for ARM devices. Don't mix core files for different platforms in the same folder.

Full package for your architecture

Recommended

If the download page offers both full and minimal packages, first-time users should choose the full package with the required runtime files and core. After extracting it, check the logs to confirm the core starts successfully; the number of files alone proves nothing.

Best for: first-time installs and anyone who wants to avoid adding files manually.

Minimal package or standalone update

Install any required runtime files and core as described in the package instructions. Make sure the versions, architecture, and folder structure match. Don't overwrite an application folder while the program is running.

Best for: users with an existing working setup who know where each component belongs.

File placement: extract everything before launching

On Windows, fully extract the archive to a permanent folder, such as D:\Apps\v2rayN, then run the main program from there. Don't launch it from an archive preview or drag only the main executable to your desktop: the core, resources, and runtime dependencies may still be inside the archive.

On macOS, if you downloaded a disk image or app bundle, follow its instructions to move the app to Applications before launching it. If you downloaded an archive, extract it first. If macOS displays a security warning on first launch, verify the download source and package before checking the app-specific warning under System Settings → Privacy & Security. Don't disable system-wide security protections.

Permanent folder

On Windows, choose a folder your account can write to. On macOS, place the app as directed by the package instructions. Avoid temporary extraction folders, and don't keep multiple copies running from different locations.
First launch

Open the main window and check the logs or status area at the bottom. If it reports a missing runtime, install the runtime for the matching architecture. Don't copy arbitrary dynamic libraries into the application folder.
Check the core

Open Settings → Parameter Settings and review the core options. Use the logs to confirm which core actually started. If the client reports a missing file, check that extraction completed and that the selected core's folder is correct.
Import a configuration

Go to Subscription Group → Subscription Group Settings, add a group, and enter its subscription URL. Save it, then select Update Subscription from the Subscription Group menu. If the menu wording differs, choose the update command for the corresponding group.
Select a server

Select a configuration in the list and set it as the active server, then check the core startup log. Having servers in the list doesn't mean one is selected for the current connection.

If security software quarantines a core file, verify the download source, then review the quarantine record and decide whether to restore it. Don't disable all protection to bypass the issue. Before updating or extracting files again, exit the app from the system tray and back up your subscription groups, routing rules, and custom settings.

Subscriptions and protocols: check key details after import

A subscription URL retrieves a list of configurations; it isn't a local proxy address. Subscriptions may contain credentials, so hide the full URL, user ID, and password in screenshots. If you have a single share link, use an import command such as Servers → Import batch URLs from clipboard. Don't paste a share link into the system proxy server field.

Check the import result first: After updating, check whether configurations appear in the group and whether the logs report a download failure, parsing error, or empty response. A successful update doesn't mean a server is reachable.
Then check the protocol: VMess and VLESS are different protocols. WebSocket is a transport, and TLS is a connection security setting; they aren't interchangeable. Keep the combination required by the server.
Choose a core that supports the configuration: Configurations using VLESS, REALITY, and similar features require a compatible core and version. Xray and V2Fly don't support exactly the same features, so switching cores isn't a universal fix.
Don't change settings blindly: The server address, port, user ID, transport path, SNI, and public key must match the server. Don't overwrite fields already set correctly by the subscription based on screenshots from another guide.

Listening ports: align client and app settings

A local listening port is the entry point browsers, the system, or command-line tools use to connect to v2rayN. It isn't the remote server's port. Go to Settings → Parameter Settings and find the local listening or inbound options. Note the actual address, port, and supported proxy types. Versions and older configurations may use different ports, so don't rely on what a guide says from memory.

127.0.0.1

Loopback address for local use

10808

Example mixed-proxy listening port in this guide

10809

HTTP port that may appear in older configurations

The two cards below assume you've confirmed that the client currently listens on 127.0.0.1:10808 in mixed mode, accepting both HTTP and SOCKS requests. If the client uses separate listeners, enter the actual port for each. Don't force both types to use the same port just to match this example.

HTTP proxy example

Proxy type: HTTP
Server: 127.0.0.1
Port: 10808
Use with: Apps that support manual HTTP proxy settings

HTTP proxies can also tunnel HTTPS connections, so there's no need to select SOCKS for HTTPS websites.

SOCKS proxy example

Proxy type: SOCKS5
Server: 127.0.0.1
Port: 10808
Command-line example: socks5h://127.0.0.1:10808

The curl socks5h syntax lets the proxy resolve the destination hostname. Check each app's documentation for its own DNS options.

For local use, keep the listener bound to loopback; there's no need to allow LAN connections. After changing the port, reload the core configuration and update any apps using a manual proxy. If the logs show address already in use, first check whether two client instances are running, then identify the process using the port instead of trying random ports one after another.

System proxy: verify the core before routing app traffic

For initial troubleshooting, leave TUN off and verify the local proxy connection first. Once the client has a working server and the core is listening, choose Set system proxy automatically from System Proxy in the main window or tray menu. This is a client menu action, not a prompt to enter a PAC script URL manually.

Windows: Go to Settings → Network & Internet → Proxy and check that the proxy address and port point to the current listening endpoint. Devices managed by an organization may restrict changes; check the applicable policy first.
macOS: Go to System Settings → Network → your current network service → Details → Proxies. Some macOS versions require authorization to change proxy settings; pay attention to permission prompts.
App coverage: Not every app follows the system proxy. Some command-line tools, games, and apps with their own proxy settings use separate network paths. One app's results don't tell you whether all traffic is working.
Before quitting: Clear the system proxy before exiting the client. If websites stop loading afterward, first check whether the system proxy still points to a local port.

Isolate issues with an explicit proxy request

On Windows, run the command below in PowerShell. In the macOS Terminal, replace curl.exe with curl. This example assumes local port 10808 accepts HTTP proxy connections. The test URL, https://example.com/, is a connectivity check, not a dedicated speed test.

curl.exe --proxy http://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com/

An HTTP response confirms that this request reached the specified proxy endpoint, but it doesn't prove that every website or UDP traffic works. If the local port can't be reached, check the listener first. If the proxy connection succeeds but TLS or remote access times out, check the server, system time, and network against the core logs. If explicit proxy requests work but the browser doesn't, check the browser's own proxy settings, extensions, and system proxy before reinstalling the client.

Common first-run issues: narrow down the cause by symptom

The window opens, but starting a server returns an error. Why?

Start with the first core error. If an executable can't be found, check the extraction folder and selected core. If a configuration field isn't supported, check the protocol and core version. If a port is in use, look for duplicate instances. Each error has a different fix; toggling the system proxy won't resolve them.

The server shows a latency result, but webpages keep loading. Why?

A latency test doesn't confirm that webpages will load. First test with an explicit proxy command, then verify the system proxy address, port, and active server. If only certain domains fail, check whether routing sends them direct and look for DNS or handshake errors in the logs. Don't change DNS, routing, and core settings all at once.

macOS asks for permission every time the app opens. What should I do?

First make sure the app is in a permanent location, not running from a mounted disk image. Check security warnings under System Settings → Privacy & Security, and check the required permissions if changing the system proxy fails. On organization-managed devices, ask your administrator about the policy. Don't run privilege-escalation commands from untrusted sources.

Why does the whole browser lose internet access after I close the client?

Check whether the system proxy still points to 127.0.0.1:10808 or an old port. Reopen the client and choose System Proxy → Clear system proxy, or restore the original proxy settings in your system network settings. If you were using a proxy provided by your organization, restore its original settings rather than disabling the proxy altogether.

Final checks: save a working setup before making advanced changes

After the initial setup works, record the settings that are working before considering startup options, routing rules, or TUN. The system proxy determines whether apps send connections to the client; routing rules determine where connections already inside the core go. These are separate steps, so enabling the system proxy doesn't mean all traffic goes through a remote server.

Confirm the app in its permanent folder launches again and the core logs show no startup errors.
Record the active subscription group, server protocol, core, and local listening port. Protect subscription credentials when making backups.
Test one explicit proxy request and one browser connection that follows the system proxy.
Test normal internet access with the system proxy cleared so you can tell whether the network is working after you quit the client.
For advanced changes, change one setting at a time. Keep copies of the previous routing, DNS, and inbound settings so you can restore them individually if something goes wrong.

For a complete walkthrough, see the client setup guide. To compare VMess and VLESS or learn about transports and core capabilities, see the protocol reference. Confirm each step—configuration imported, core started, port reachable, and app using the proxy—instead of repeatedly downloading and reinstalling the package.