npm Behind Proxy: Configure for Corporate Networks (2026)

npm, the Node Package Manager, often throws a wrench into corporate network setups due to proxy servers.

Here’s how to get npm playing nice with your company’s network:

The Problem: npm Can’t Reach the Registry

Your corporate network likely uses a proxy server to control internet access and for security reasons. By default, npm isn’t aware of this proxy, so when you try to install packages (npm install), it attempts to connect directly to the npm registry (registry.npmjs.org) and fails, usually with a timeout error or an "ECONNREFUSED" message. The proxy server is silently blocking these unsolicited outgoing connections.

Common Causes and Solutions

No Proxy Configuration in npm:
- Diagnosis: Check your current npm proxy settings.
```
npm config get proxy
npm config get https-proxy
```
  If these commands return nothing or undefined, npm isn’t configured.
- Fix: Set the proxy for both HTTP and HTTPS. You’ll need your proxy server’s address and port. If your proxy requires authentication, include your username and password.
```
# For HTTP proxy
npm config set proxy http://your_proxy_address:proxy_port

# For HTTPS proxy (often the same as HTTP proxy)
npm config set https-proxy http://your_proxy_address:proxy_port

# If your proxy requires authentication
npm config set proxy http://username:password@your_proxy_address:proxy_port
npm config set https-proxy http://username:password@your_proxy_address:proxy_port
```
  Replace your_proxy_address, proxy_port, username, and password with your actual corporate proxy details.
- Why it Works: This tells npm to route all its registry requests through the specified proxy server, which is allowed by your network.
Incorrect Proxy Authentication:
- Diagnosis: You’ve set proxy details, but npm install still fails with authentication errors (e.g., "407 Proxy Authentication Required").
- Fix: Double-check your username and password. Ensure there are no typos and that the password doesn’t contain special characters that might be misinterpreted in the URL. If it does, you might need to URL-encode the password. For example, a space becomes %20.
```
# Example with URL-encoded password
npm config set proxy http://username:my%20password@your_proxy_address:proxy_port
npm config set https-proxy http://username:my%20password@your_proxy_address:proxy_port
```
- Why it Works: The proxy server requires specific credentials to grant access. Correctly formatted credentials allow the proxy to authenticate your requests.
Firewall Blocking npm’s Traffic (Even Through Proxy):
- Diagnosis: Proxy is configured correctly, but you still get timeouts or connection refused errors. The corporate firewall might be inspecting or blocking traffic to registry.npmjs.org on port 443 (HTTPS) even when it’s supposed to go through the proxy.
- Fix: You may need to ask your IT department to whitelist registry.npmjs.org and potentially *.npmjs.org for outgoing connections on port 443, or ensure your proxy is configured to allow this specific traffic. Sometimes, it’s necessary to configure npm to use a specific CA certificate if your company’s proxy uses SSL interception. You can set this with:
```
npm config set cafile /path/to/your/corporate/ca.crt
```
  (Get the ca.crt file from your IT department).
- Why it Works: This ensures that network security devices explicitly permit npm’s traffic to reach the registry, either by whitelisting or by providing the necessary trust certificates for SSL inspection.
Outdated npm Version:
- Diagnosis: Newer npm versions have improved proxy handling and security features. If you’re on a very old version, it might have bugs or limitations.
```
npm --version
```
- Fix: Update npm to the latest version.
```
npm install -g npm@latest
```
- Why it Works: Updates often contain bug fixes and enhance compatibility with modern network infrastructures and security protocols.
Proxy Environment Variables Conflict:
- Diagnosis: You’ve set npm proxy configurations, but it still doesn’t work. Your system might also have HTTP_PROXY or HTTPS_PROXY environment variables set, which can sometimes interfere or take precedence in unexpected ways.
```
echo $HTTP_PROXY
echo $HTTPS_PROXY
```
- Fix: Unset these environment variables or ensure they are correctly configured to match your npm settings.
```
# In bash/zsh
unset HTTP_PROXY
unset HTTPS_PROXY

# In Windows Command Prompt
set HTTP_PROXY=
set HTTPS_PROXY=

# In Windows PowerShell
$env:HTTP_PROXY = ""
$env:HTTPS_PROXY = ""
```
  After unsetting, re-apply your npm proxy configuration.
- Why it Works: npm can be configured via its own config files or through system environment variables. When both are present, their interaction can be unpredictable. Explicitly configuring npm and ensuring no conflicting environment variables are set provides a clear, single source of truth for proxy settings.
npm config set registry is Incorrect:
- Diagnosis: You might be trying to use a private npm registry or a mirror, and its URL is either wrong or not accessible through your proxy.
```
npm config get registry
```
- Fix: Ensure the registry URL is correct and accessible. If you’re using the public npm registry, it should be:
```
npm config set registry https://registry.npmjs.org/
```
  If you are using a private registry, ensure its address is correct and that your proxy allows access to it.
- Why it Works: npm needs to know the correct address of the package registry. An incorrect or inaccessible registry URL will prevent package installation, regardless of proxy settings.

After applying these fixes, the next error you might encounter is related to certificate validation if your corporate network performs SSL inspection and you haven’t configured npm to trust its certificate authority.