npm Config: Every .npmrc Setting Explained (2026)

npm’s configuration is surprisingly dynamic, and the .npmrc file is just one piece of a much larger, often overridden, puzzle.

Let’s see it in action. Imagine you’re in a project directory.

# First, let's see what npm thinks our config is, globally and locally
npm config list -l

This command spits out a LOT. You’ll see settings from multiple sources:

• Built-in defaults: npm’s own internal settings.
• User config: ~/.npmrc
• Project config: ./.npmrc
• Environment variables: NPM_CONFIG_SETTING_NAME
• Command-line flags: npm --setting-name=value install

The effective configuration is a merge of these, with later sources overriding earlier ones. This is why a setting in your project’s .npmrc can override a global one, and why running npm install --no-save temporarily disables the save behavior without touching any files.

The core problem npm config solves is standardizing how developers and CI/CD systems interact with the npm registry and npm itself. Without it, every install would require manual flags or environment variable setups, leading to inconsistencies and errors.

The .npmrc Landscape

npm uses a hierarchy for configuration. When you run an npm command, it consults these sources in order:

1. Defaults: These are baked into npm itself. You rarely touch these directly.
2. Environment Variables: Any variable prefixed with NPM_CONFIG_ is picked up. For example, NPM_CONFIG_REGISTRY=https://my.private.registry.com sets the registry. These have high precedence.
3. User Configuration (~/.npmrc): This file affects all your projects unless overridden.
4. Project Configuration (./.npmrc): This file, located in your project’s root directory, overrides user configuration for that specific project.
5. Command-line Flags: Flags passed directly to an npm command (e.g., npm install --registry=...) have the highest precedence and override everything else.

Key .npmrc Settings and Their Impact

Let’s break down some of the most impactful settings you’ll find in .npmrc files.

• registry:

  • What it does: Specifies the URL of the npm registry to use for fetching packages.
  • Example:

    registry=https://registry.npmjs.org/
    

    or for a private registry:

    registry=https://my.private.registry.com/
    

  • Why it matters: Essential for accessing public packages or directing npm to your organization’s private package source.

• scope:

  • What it does: Defines a scope for packages, typically used with private registries or for organizing packages. When you publish or install packages prefixed with this scope (e.g., @myorg/my-package), npm will use the registry associated with that scope.
  • Example:

    @myorg:registry=https://my.private.registry.com/
    scope=myorg
    

  • Why it matters: Crucial for managing private packages within an organization without them clashing with public ones.

• //registry.npmjs.org/:_authToken:

  • What it does: Provides authentication tokens for specific registries. The format //<registry-hostname>/:_authToken=<token> is used. This is how npm authenticates with private registries or when publishing to the public registry.
  • Example:

    //registry.npmjs.org/:_authToken=abcdef1234567890
    

    or for a private registry:

    //my.private.registry.com/:_authToken=fedcba0987654321
    

  • Why it matters: This is how npm proves your identity to the registry, allowing you to install private packages or publish your own.

• save:

  • What it does: Determines whether packages are automatically saved to package.json when installed. true saves them to dependencies, false does not.
  • Example:

    save=true
    

  • Why it matters: Controls the default behavior of npm install <package>, ensuring your project’s dependencies are tracked. Setting save=false is common in CI environments.

• save-prefix:

  • What it does: Sets the default prefix for version numbers when saving dependencies. Common values are ~ (allows updates to the latest patch version) or ^ (allows updates to the latest minor version).
  • Example:

    save-prefix=~
    

  • Why it matters: Influences how package updates are handled by default, impacting the stability and upgradability of your project.

• strict-ssl:

  • What it does: Controls whether npm verifies the SSL certificate of the registry. Set to true (default) for security, false to disable certificate checks (not recommended for production).
  • Example:

    strict-ssl=true
    

  • Why it matters: A critical security setting. Disabling it can expose you to man-in-the-middle attacks, especially when connecting to untrusted networks or registries.

• fetch-retries, fetch-retry-mintimeout, fetch-retry-maxtimeout:

  • What they do: Configure how npm retries network requests when they fail. fetch-retries is the number of retries, and the other two define the minimum and maximum delay between retries in milliseconds.
  • Example:

    fetch-retries=5
    fetch-retry-mintimeout=2000
    fetch-retry-maxtimeout=10000
    

  • Why they matter: Help npm overcome transient network issues, making installations more robust, especially in unstable network environments.

• proxy and https-proxy:

  • What they do: Specify proxy server URLs for HTTP and HTTPS requests, respectively.
  • Example:

    proxy=http://localhost:8888
    https-proxy=http://localhost:8888
    

  • Why they matter: Essential for developers working behind corporate firewalls or network proxies.

• email:

  • What it does: Your email address, often used during npm login or npm publish.
  • Example:

    email=your.email@example.com
    

  • Why it matters: Primarily for authentication and identification when interacting with the npm registry.

The way npm resolves configuration values is a layered approach, where settings closer to the command execution (command-line flags, project .npmrc) override those further away (user .npmrc, environment variables, defaults). This allows for both global defaults and highly specific overrides for individual projects or even single commands.

One aspect that often trips people up is how npm config set interacts with these layers. When you run npm config set key value, it tries to write to the closest .npmrc file. If you’re in a project directory, it writes to ./.npmrc. If you’re not in a project directory and haven’t explicitly set a user config file location, it writes to ~/.npmrc. This behavior can be surprising if you’re not paying attention to your current working directory.

The next thing you’ll likely grapple with is managing different npm configurations for different projects or environments, leading you to explore tools like npx for one-off commands or more advanced package management strategies.