# npm proxy settings: npmrc, precedence and install failures

Source: https://ipvolt.com/guides/npm-proxy-settings
Markdown: https://ipvolt.com/guides/npm-proxy-settings.md

[Home](https://ipvolt.com/index.md) / [Guides](https://ipvolt.com/guides.md) / [npm proxy settings: npmrc, precedence and install failures](https://ipvolt.com/guides/npm-proxy-settings.md)

Category: Integration
Published: 2026-10-13
Reading time: 9 minutes
Author: ipvolt

Set npm proxy and https-proxy, resolve npmrc and environment conflicts, verify package downloads, and fix trust or routing without disabling TLS checks.

For npm registry traffic, inspect **both `proxy` and `https-proxy`**, choose one approved gateway, and test the package download as well as registry access. A successful `npm ping` is insufficient to prove an installation will work. In our controlled test, ping and package metadata succeeded while the tarball request failed.

This guide's observations use **npm11.19.1, Node26.10.0 and macOS15.7.4**, recorded on 12 October 2026. Nine routing cases and four configuration-edit checks passed their stated acceptance criteria. The fixtures use an HTTP registry and forwarding proxies on loopback; they do not test HTTPS, certificates, proxy authentication or a commercial service.

## Distinguish the gateway from the registry

`registry` identifies the service supplying package metadata. `proxy` and `https-proxy` configure the network gateway used to reach it. A Nexus “npm proxy repository” is a repository manager/cache exposed as an npm registry; it is a different layer from a forward HTTP proxy. Use your organization's registry URL and gateway as separate inputs. [Sonatype npm configuration](https://help.sonatype.com/en/configuring-npm.html), [npm configuration](https://docs.npmjs.com/cli/v11/using-npm/config/).

Start inside the project where the failure occurs:

```sh
node --version
npm --version
npm config get registry
npm config get proxy https-proxy noproxy
npm config get userconfig globalconfig
```

Inspect this output locally; proxy URLs can contain credentials. The registry URL is not evidence of the network route. Neither are `null` proxy values: our raw `HTTP_PROXY` case still used a proxy while npm displayed `null` for both configuration keys.

## Test registry access, metadata and the archive

After inspecting the failing project, choose four explicit inputs: `NPM_PROXY_URL` for the approved gateway, `NPM_REGISTRY_URL` for the approved registry, `NPM_PACKAGE` for an unscoped package pinned as `NAME@VERSION`, and `NPM_USERCONFIG` for an approved absolute npmrc path. The userconfig path reported above is a starting point; ensure the chosen file supplies any required registry authentication. No tokens need to be copied into the diagnostic directory.

For a private or scoped package, the approved configuration must preserve the appropriate registry and registry-scoped authentication. An `@scope:registry` entry is a distinct setting: do not assume the default `--registry` overrides it. Confirm the metadata's archive URL and the actual registry used. The basic commands below choose an unscoped package to isolate the gateway check. [npmrc scope and authentication](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/).

An HTTP gateway may be used for an HTTPS registry; the gateway URL's scheme identifies its own connection protocol. Keep actual secrets out of shell-history literals and shared logs. Environment substitution does not conceal the expanded argument from local process inspection.

Run all three checks in one new directory outside existing projects. Keep the same registry, approved config and proxy values, with a new cache path for each request stage:

```sh
npm_proxy_check_dir="$(mktemp -d)"
cd "$npm_proxy_check_dir" || exit 1

npm ping --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-ping" \
  --fetch-retries=0 --fetch-timeout=10000

npm view "$NPM_PACKAGE" version dist.tarball --json \
  --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-view" \
  --fetch-retries=0 --fetch-timeout=10000
```

`ping` probes the registry; `view` reads metadata, including the archive URL. Neither downloads and verifies the package archive. [npm ping](https://docs.npmjs.com/cli/v11/commands/npm-ping/), [npm view](https://docs.npmjs.com/cli/v11/commands/npm-view/).

For the third check, stay in that diagnostic directory and use the same inputs:

```sh
npm install "$NPM_PACKAGE" --ignore-scripts --no-audit --no-fund \
  --no-package-lock --save=false \
  --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-install" \
  --fetch-retries=0 --fetch-timeout=10000
```

Inspect the installed package's expected name, version and contents. Our fixture checks exact payload files, rather than accepting an HTTP200 or successful metadata response. The fresh installation cache prevents a previously cached archive from silently satisfying this check. Also verify the gateway's request logs when available: a valid package alone does not prove which route carried it. Keep the diagnostic output for review and remove the temporary directory when finished.

The install disables package installation scripts. It checks registry-package retrieval, not every dependency or a project's complete installation behavior. `fetch-timeout` and disabled fetch retries bound individual fetch behavior; they are not a ten-second deadline for the whole installation. [npm install](https://docs.npmjs.com/cli/v11/commands/npm-install/), [npm fetch options](https://docs.npmjs.com/cli/v11/using-npm/config/).

## Resolve configuration conflicts before saving settings

For the **same key**, npm's documented priority runs from command options to `npm_config_*` environment values, then project, user and global configuration. The project's `.npmrc` can keep overriding a new user setting. Project configuration is not read in global install mode. [Pinned npm configuration hierarchy](https://github.com/npm/cli/blob/v11.19.1/workspaces/config/README.md), [npmrc files](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/).

That hierarchy does not settle conflicts between different keys. In our npm11.19.1 case, a user `https-proxy=A` remained active despite a command `--proxy=B`. Both values survived configuration resolution, and the registry fetch implementation selected `httpsProxy || proxy`—even for our HTTP registry. Inspect and align both keys when you intend one gateway. [Pinned registry fetch implementation](https://raw.githubusercontent.com/npm/cli/v11.19.1/node_modules/npm-registry-fetch/lib/index.js).

After the temporary test works, save credential-free illustrative values to the intended file:

```sh
npm config set proxy=http://proxy.example:8080 \
  https-proxy=http://proxy.example:8080 --location=user
```

Use `--location=project` from the relevant project if that is the desired scope. Keep credentials out of committed `.npmrc` files. npmrc supports environment substitutions for values; a configuration lookup can still display the expanded value. Registry tokens also have their own registry scope and are not proxy credentials. [npmrc authentication and substitutions](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/).

## What our routing fixture showed

The [routing lab](https://ipvolt.com/downloads/npm-proxy-settings/npm-proxy-lab.mjs) creates a fake registry and proxies A/B, serves a real generated package archive and records each actual request. The [results](https://ipvolt.com/downloads/npm-proxy-settings/results.json) include exact command arguments, configuration and payload acceptance.

| Controlled conflict | Observed route/outcome | Diagnostic value |
| --- | --- | --- |
| No proxy settings/environment | Direct; payload verified | Baseline |
| User npmrc sets both keys A | A; payload verified | User config works in this fixture |
| Project B over user A, both keys | B; payload verified | Inspect the project file |
| `npm_config_proxy` and `npm_config_https_proxy` A over project B | A; payload verified | Inspect process configuration environment |
| Command sets both keys B over config environment A | B; payload verified | Compare like keys at the same layer |
| Only raw `HTTP_PROXY=A`, displayed values null | A; payload verified | npm config output is incomplete route evidence |
| Raw `NO_PROXY=127.0.0.1` plus user proxy A, displayed noproxy empty | Direct; payload verified | A raw bypass can remain active |
| B allows ping and metadata, rejects archive | Ping/view succeed; install failsE502, package absent | Check the archive request separately |
| User `https-proxy=A`, project/command `proxy=B` | A; payload verified | Command priority for one key does not erase the other |

Eight installations verified the expected package payload. The ninth was an intentional failure with no installed payload; all nine cases met their defined acceptance criteria. Raw environment fallback comes from the tested agent implementation. The bypass observation covers only the exact IPv4 loopback hostname, not wildcard, CIDR or every client. [Pinned npm agent](https://raw.githubusercontent.com/npm/agent/v4.0.2/lib/proxy.js).

## Remove values from the intended file

Inspect the project `.npmrc` and the user/global paths reported earlier. If you meant to remove the example user settings:

```sh
npm config delete proxy https-proxy --location=user
```

A project entry can still win. Remove project settings only when that is intended, from the project directory:

```sh
npm config delete proxy https-proxy --location=project
```

Our four separate configuration-edit checks show that deleting user keys preserved the project's values; deleting the project keys then removed the effective pair in that isolated configuration. npm's documentation says deletion removes keys from all files, but the pinned npm11.19.1 implementation and our experiment act on the selected location. Use explicit scope and verify the result. [Pinned deletion implementation](https://raw.githubusercontent.com/npm/cli/v11.19.1/lib/commands/config.js), [npm config documentation](https://docs.npmjs.com/cli/v11/commands/npm-config/).

Also inspect the actual process's `npm_config_proxy`, `npm_config_https_proxy`, `HTTP_PROXY`, `HTTPS_PROXY` and bypass variables. Removing file entries does not remove environment values. The [environment variables guide](/guides/proxy-environment-variables) explains how inherited settings differ by client.

## Diagnose remaining failures

| Failure stage | Next check |
| --- | --- |
| No gateway connection | Host/port, selected config and process bypass settings |
| Registry access succeeds, archive fails | `dist.tarball` host/path, gateway policy and archive request; account for cache |
| Proxy407 | Gateway authentication; use the [407 guide](/guides/fix-proxy-error-407) |
| Registry authentication error | Token, registry and scope; keep this separate from gateway credentials |
| Certificate verification error | Approved CA trust and hostname for the actual failing connection |
| Git dependency or install-script download fails | Use [Git proxy setup](/guides/git-proxy-setup) for HTTP(S) Git downloads; check each install script's client separately. npm registry settings do not establish those routes |

For corporate CA trust, npm documents `cafile` and `strict-ssl`. Obtain the approved CA bundle from your administrator and keep `strict-ssl` enabled. The HTTP fixtures do not verify any HTTPS or corporate trust fix. [npm certificate configuration](https://docs.npmjs.com/cli/v11/using-npm/config/).

## Reproduce the two experiments

Download the two scripts and [README](https://ipvolt.com/downloads/npm-proxy-settings/README.md) into one directory, then run with Node and npm installed:

```sh
node npm-proxy-lab.mjs ./local-results.json
node npm-config-edit-check.mjs ./local-config-results.json
```

The [configuration script](https://ipvolt.com/downloads/npm-proxy-settings/npm-config-edit-check.mjs) and [config results](https://ipvolt.com/downloads/npm-proxy-settings/config-edit-results.json) accompany the routing evidence. They use explicit temporary user/global config paths and caches, preserve your original user configuration and confine network requests to loopback. The recorded environment was npm11.19.1/Node26.10.0; the current v11 docs display a newer version, so rerun before generalizing to another release. No extra npm packages are required to run these fixtures. HTTPS/CONNECT, proxy credentials, private registry authentication, Git dependencies, existing lockfiles and lifecycle downloads remain outside the experiment.

If you are evaluating ipvolt for future proxy workflows, [Know when access opens.](https://ipvolt.com/#waitlist-hero) One email when access opens. Nothing else.

## Sources & further reading

- [npm config](https://docs.npmjs.com/cli/v11/using-npm/config/)
- [npmrc](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/)
- [Pinned npm registry fetch](https://raw.githubusercontent.com/npm/cli/v11.19.1/node_modules/npm-registry-fetch/lib/index.js)

## Related guides

- [Proxy environment variables: HTTP_PROXY and NO_PROXY](https://ipvolt.com/guides/proxy-environment-variables.md)
- [Fix proxy error 407 without guessing](https://ipvolt.com/guides/fix-proxy-error-407.md)
- [Use a proxy with Node.js fetch](https://ipvolt.com/guides/nodejs-fetch-proxy.md)
- [Git proxy setup: HTTPS, config scope and safe removal](https://ipvolt.com/guides/git-proxy-setup.md)

## About ipvolt

Examples use generic proxy settings, with links to the original technical documentation. Product-specific behavior must be checked with your provider. ipvolt is still in development.

## Know when access opens.

ipvolt · In development

We’re building proxy infrastructure for developers and data teams. Join the interest list for a heads-up when ipvolt is ready.

Consent: One email when access opens. Nothing else.

[Get early access](https://ipvolt.com/guides/npm-proxy-settings#waitlist-closing). Use the email form on this page to join the interest list.

[Privacy](https://ipvolt.com/privacy)