Why a Browser Can Work While npm and pip Fail
A common developer setup looks healthy at first: Clash is running, a browser can open sites through a proxy, but npm install stalls or pip install fails to reach a package index. This does not necessarily mean the proxy node is down. Browsers often use the system proxy settings, a browser extension, or a proxy configured directly in the application. Terminal programs may use none of these settings.
Clash TUN mode addresses this gap by creating a virtual network interface and routing eligible device traffic through the Clash core. Instead of relying on each application to understand HTTP proxy settings, TUN can capture network packets from applications such as Node.js, Python, Git, and command-line download tools. Clash then applies the configuration’s routing rules to decide whether each connection should use a proxy group, go DIRECT, or be blocked.
That distinction matters: enabling TUN does not automatically mean every request uses a proxy. In rule mode, TUN captures traffic, but the rules still determine its route. A package registry request that matches a DIRECT rule will remain direct; one that reaches a proxy rule can use the selected proxy group. DNS behavior, operating-system permissions, and the active network interface can also affect the result.
What You Will Achieve
Route terminal package downloads consistently, verify the path with practical tests, and isolate whether a failure comes from TUN, DNS, Clash rules, or the package manager itself.
This guide uses Mihomo-based clients such as Clash Verge Rev as examples. Menu names vary between clients and versions, so use the equivalent TUN or service-mode setting in your application. Keep your existing subscription and proxy groups; the examples below are additions or checks, not a complete replacement profile.
1Prepare Clash TUN and Check Permissions
Before changing package-manager settings, confirm that the Clash core supports TUN and that the operating system has allowed the client to create or manage a virtual interface. On desktop systems, this commonly requires administrator approval, a privileged service, or permission to install a network extension. If the TUN switch immediately turns itself off, check the client’s notification, service, or core log before editing YAML.
Enable TUN in Your Client
In Clash Verge Rev, open the settings area and locate the TUN option. Depending on the release, you may need to install or start the service component first. Turn TUN on, approve any operating-system prompt, and confirm that the client reports the feature as active. Other Mihomo-based clients may expose the same controls under General, Network, or Service settings.
If you manage the profile directly, Mihomo configurations commonly use a section similar to this:
Do not paste this block blindly over an existing tun: section. YAML configurations should have a single key at each level; duplicate keys can be rejected or interpreted differently by parsers. Merge the required options into the existing section, save a backup first, and reload the profile. Options supported by the core can differ by version and operating system, so use the configuration documentation for the Mihomo build bundled with your client.
Understand Platform Permissions
- Windows: Start the client with the permissions requested for TUN or its service. If the client offers a service installation step, complete it and restart the client. Also check whether another VPN or network filter is competing for the default route.
- macOS: Approve the network extension or system prompt shown by the client. If the prompt was dismissed, review the relevant system settings and restart the client after granting permission. Avoid repeatedly launching multiple proxy clients while testing.
- Linux: TUN creation and route management may require elevated privileges or suitable capabilities. Follow the client’s service setup instructions, and check that the system has a TUN device available. Do not run every development command as root just to compensate for a TUN permission problem.
Keep the Scope Clear
TUN is a device-level network feature, not a package-manager setting. Do not expose Clash’s local controller or proxy port to a public network as a workaround. Keep the client’s management interface protected and use only the local access intended by your setup.
2Make Sure Registry Traffic Matches the Right Rules
Once TUN is active, inspect the profile’s routing mode and rules. In Rule mode, traffic is evaluated from top to bottom, and the first matching rule determines the policy. TUN can capture a connection without forcing it to a proxy. If an earlier rule sends the destination DIRECT, a later registry-specific rule will never take effect.
For common package downloads, the relevant hosts include registry.npmjs.org for npm and pypi.org plus files.pythonhosted.org for pip. A package manager may also contact additional hosts for authentication, mirrors, metadata, or project-specific resources. Start by checking the actual requests in Clash’s connection or traffic view rather than assuming every install uses only one domain.
If your policy is to proxy these registries in Rule mode, add targeted rules before broad catch-all rules and use the name of a proxy group that already exists in your profile:
Replace YourProxyGroup and YourExistingFinalPolicy with valid names from your configuration. If your rules already cover these domains through a broader policy, avoid adding redundant entries. A rule referencing a group that does not exist can make the configuration invalid or cause an unexpected route. After editing, reload the profile and confirm the active policy shown for a test connection.
Global mode is useful as a short diagnostic: if a terminal request works in Global mode but fails in Rule mode, the problem is likely a rule or policy selection rather than TUN capture itself. Return to your intended mode after testing. Global mode sends much more traffic through the selected proxy and is not a substitute for a carefully maintained rule set.
Check DNS Without Guessing
Package managers need to resolve hostnames before connecting. If the browser succeeds but terminal tools report name-resolution errors, check whether DNS requests are being intercepted and handled as intended. Mihomo users often enable its DNS service and choose an enhanced mode appropriate for their profile, but DNS settings must be compatible with the client, upstream resolvers, and existing rules. Do not add a second conflicting DNS configuration just to copy an example from another setup.
From a terminal, use the operating system’s available DNS tool to check resolution:
A returned address confirms that the name resolved; it does not by itself prove that the later HTTPS connection used a proxy. If DNS fails, inspect the Clash DNS log, verify that the DNS feature is enabled where intended, and check whether another VPN, local DNS filter, or security product is intercepting requests. Do not publish resolver output or full configuration files if they contain private server details or credentials.
3Verify npm and pip from the Command Line
Test in layers so a failure points to a specific part of the path. First confirm that Clash is running and TUN is active. Then check that the target domains resolve, make a simple HTTPS request, and finally ask the package manager for metadata. Keep the Clash connection or traffic panel open while testing; a matching connection entry is useful evidence that the request reached the core.
Test npm
Check npm’s configured registry and request package metadata:
The standard registry is typically https://registry.npmjs.org/, though projects and organizations may use a private registry or mirror. If the metadata request succeeds, try installing a small dependency in a disposable project rather than changing a production project during diagnosis. For example, create an empty test directory, initialize a package, and install a package there. This separates network behavior from a lockfile, lifecycle script, or project-specific configuration issue.
Also inspect whether npm has an explicit proxy configured:
An explicit proxy can be useful when intentionally using Clash’s local HTTP proxy, but it is not required merely because TUN is enabled. Leaving an old proxy value in npm’s configuration can send requests to a stale address or create confusing behavior. If you choose TUN as the transport, remove only settings you know are obsolete; do not delete organization-required registry or authentication configuration.
Test pip
Check pip’s index configuration and query a known package:
On systems where python refers to a different installation, use the appropriate interpreter command, such as python3 -m pip. A virtual environment can help keep the test separate from system Python. Pip may use settings from configuration files, environment variables, or command-line options; a configured private index or mirror can change which hostname needs to be reachable.
When a command fails, note the exact error and timestamp, then correlate it with Clash’s connection log. A connection entry with a DIRECT policy suggests a routing decision to review. No entry at all can indicate that TUN is inactive, traffic is excluded, or the application is using a route outside the expected interface. A connection using the intended proxy group that still fails points more toward the node, remote DNS, TLS inspection, or the registry itself.
Use a Simple HTTPS Request as a Control
If curl is installed, test the registry endpoints directly:
HTTP status codes such as 200, 301, or another expected response show that an HTTPS server answered; the exact result depends on the endpoint. A timeout, certificate error, or name-resolution error narrows the investigation. Remember that command-line tools may honor their own proxy environment variables. To test TUN specifically, inspect and account for variables such as HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, so an explicit application proxy is not mistaken for TUN interception.
4Troubleshoot Common Terminal Failures
Use the error category as a clue rather than changing several settings at once. Make one change, repeat the same test, and compare the result. This keeps the diagnosis reproducible and reduces the risk of breaking a working browser or other applications.
| Symptom | Likely area | What to check |
|---|---|---|
| “Could not resolve host” or name-resolution timeout | DNS or local resolver path | Check the Clash DNS log, system resolver, and whether another network tool is intercepting DNS. |
| Connection timeout with no matching Clash entry | TUN activation, permission, or interface routing | Confirm TUN is active, approve required permissions, and check for competing VPNs or route managers. |
| Connection appears as DIRECT but should use a proxy | Rule order or policy selection | Review earlier matching rules and confirm that the intended rule points to a valid proxy group. |
| Request reaches the proxy group but still fails | Proxy node, remote DNS, TLS, or registry | Try a healthy node, inspect the core log, and compare with another known HTTPS destination. |
| npm or pip uses an unexpected host | Custom registry, mirror, or project configuration | Inspect the active registry and package-manager configuration before adding domain rules. |
Certificate errors deserve particular care. Do not disable TLS verification as a permanent fix: doing so weakens protection against interception and can hide a genuine certificate or system-clock problem. Check that the device clock is correct, that the selected proxy does not interfere with TLS, and that any organization-managed certificate setup is still in place.
Permission errors during TUN startup are different from a package-manager permission error. If the TUN interface cannot start, resolve the client or operating-system permission first. If TUN is active but a package installation says it cannot write to a directory, address the package manager’s local permissions or use an appropriate project environment; changing network routes will not fix filesystem access.
Interference from other network tools can produce intermittent results. VPN clients, endpoint security software, container networking, virtual machines, and custom firewall rules may alter routes or DNS behavior. For a controlled test, temporarily stop only tools you are authorized to manage, change one variable at a time, and restore your normal configuration afterward. On managed work devices, consult your organization’s IT policy before changing network services.
Practical Debugging Order
Check TUN status, confirm DNS resolution, inspect the Clash connection entry, verify the matched rule and policy, then test the package manager. This sequence separates capture, resolution, routing, and application configuration.
5Frequently Asked Questions
Do I need TUN if I set npm’s proxy?
No. An explicit npm proxy can route npm’s supported HTTP or HTTPS requests through Clash’s local proxy port without device-level TUN. TUN is useful when you want applications that do not honor proxy settings to follow Clash routing rules. Choose one method for a clean test, or use both only when you understand which application and traffic each method controls.
Why does my browser work while pip still times out?
The browser may use system proxy settings while pip does not. TUN can capture pip’s network traffic, but only when it is active, permitted, and not bypassed by another route. Check whether pip is using a private index, whether DNS resolves, and whether the corresponding connection appears in Clash’s traffic view.
Does TUN force npm and pip through the selected proxy?
No. TUN captures eligible traffic, while Clash’s mode and rules determine the policy. In Rule mode, a matching DIRECT rule stays direct. Add or adjust targeted rules only if that matches your intended routing policy, and place them before rules that would otherwise match first.
What information should I collect before asking for help?
Record your operating system, Clash client and Mihomo core version, TUN status, package-manager error, active registry or index, and the matched policy shown in the connection log. Redact subscription URLs, credentials, private hostnames, and tokens before sharing configuration or logs.
With TUN permissions in place, DNS resolving correctly, and registry traffic matching the intended policy, npm and pip can use the same dependable routing path as other device applications. Keep the configuration minimal, verify changes with repeatable command-line tests, and revisit the rules whenever your project switches to a private registry or mirror.