What Is .npmrc and How Does It Work?

The .npmrc file is a configuration file used by npm (Node Package Manager) to define persistent settings that control package installation, publishing, registry behavior, and script execution. It uses a simple key = value syntax, with full support for boolean flags, strings, lists, and scoped registry overrides.

Unlike many configuration systems, npm supports multiple .npmrc files at different levels of scope. This design allows organizations to enforce corporate policy while still granting developers flexibility for personal preferences.

Configuration Precedence Hierarchy

Understanding precedence is critical because npm merges configuration from up to four sources simultaneously. When the same key appears in multiple locations, the higher-precedence source wins.

How npm Merges Multiple .npmrc Files

npm does not simply use the last-found value. It performs a deep merge across all four sources. For keys that support array values (such as always-auth or custom fields), lower-precedence sources fill in gaps that higher-precedence sources do not explicitly override.

For scalar values like registry, cache, or scope, the highest-precedence source completely overrides all lower ones. This means a single registry line in your project .npmrc will silence any global or user-level registry setting for that project.

.npmrc File Locations and File System Structure

Each .npmrc location serves a different purpose in the development lifecycle. Confusion about where settings are resolved is one of the most common sources of "it works on my machine" issues in npm-based projects.

Location 1: Project-Level .npmrc

The project-level .npmrc lives at the root of your repository. This is the most important file for reproducible builds because every developer and every CI runner reads the same settings.

# Example project .npmrc
registry=https://registry.npmjs.org/
engine-strict=true
package-lock=true
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Best practice: Commit this file to version control, but exclude secret tokens. Use environment variable substitution (${VAR_NAME}) for any credentials.

Location 2: User-Level ~/.npmrc

The user-level .npmrc resides in the home directory of the current user. It applies across all projects on that machine and is typically used for personal preferences such as default editors, notification settings, or a personal registry mirror.

Find your user-level config path by running:

npm config get userconfig
# Output: /home/username/.npmrc

Location 3: Global .npmrc

The global configuration file is managed by npm itself and typically lives in the npm installation prefix directory. This file is intended for system administrators who want to set defaults for all users on a shared machine.

npm config get globalconfig
# Output: /usr/local/etc/npmrc

Location 4: Environment Variables

npm reads configuration from environment variables prefixed with NPM_CONFIG_. These override every .npmrc file and are the standard mechanism for injecting configuration into containerized or CI environments.

export NPM_CONFIG_REGISTRY=https://private-registry.example.com
export NPM_CONFIG_CACHE=/tmp/npm-cache

Hidden Config: .npmrc in Node Modules

Certain packages ship with their own .npmrc files inside node_modules/. npm does not read these by default during installation. However, packages may use them to configure their own build scripts when run directly. Do not assume that a package's .npmrc affects your top-level install behavior.

Common .npmrc Configuration Options

The following table catalogs the most frequently used .npmrc keys, their defaults, and their practical impact on package management workflows. Values that are commonly changed by development teams are flagged.