Why npm install Rewrites package-lock.json: Mechanisms and Evolution of Dependency Locking

Introduction

In the Node.js ecosystem, the introduction of the package-lock.json file aims to ensure deterministic and consistent dependency installations. However, many developers upgrading to npm 5 observed that running npm install rewrites this file, seemingly contradicting the purpose of a lock file. Based on npm documentation, community discussions, and practical cases, this article systematically analyzes the reasons, evolution, and solutions for this phenomenon.

Purpose and Design Intent of package-lock.json

package-lock.json records the exact versions of each package in the dependency tree, including transitive dependencies. Its core objectives are:

• Ensuring identical dependency versions across different environments (development, testing, production).
• Providing reproducible builds to avoid behavioral differences due to floating dependency versions.
• Accelerating installation by reducing network requests through caching and exact version matching.

For example, if package.json declares:

"dependencies": {
  "typescript": "^2.1.0"
}

After the first npm install, package-lock.json might lock TypeScript at version 2.1.6. Other developers pulling the code and running npm install would then install 2.1.6, not potentially available 2.4.1.

Behavioral Evolution and Rewriting Mechanism of npm install

Prior to npm 5.1.0, package-lock.json was treated as the highest priority dependency source. However, starting from this version, behavior changed: package.json can override package-lock.json. The specific mechanism is as follows:

• When dependency declarations in package.json (e.g., ^2.1.0) allow updates to newer versions, npm install checks the registry and, if a new version (e.g., 2.4.1) is found, installs it and updates package-lock.json.
• This design balances locking and updating: the lock file ensures current state consistency but allows automatic fetching of fixes or feature updates when compliant with package.json ranges.

Consider the following scenario:

// package.json
"dependencies": {
  "lodash": "^4.17.0"
}

// package-lock.json (initial)
"lodash": {
  "version": &4.17.21"
}

If lodash releases 4.18.0, running npm install may update the lock file to 4.18.0, as ^4.17.0 allows minor version updates.

Strict Dependency Locking Implementation: The npm ci Command

To address potential indeterminism in npm install, npm 5.7.0 introduced the npm ci command:

• Installs dependencies solely based on package-lock.json, completely ignoring version ranges in package.json.
• If package.json is incompatible with the lock file (e.g., declared version exceeds the locked range), the command errors out instead of proceeding.
• Suitable for continuous integration (CI) environments, ensuring builds strictly match the lock file.

Example comparison:

// Scenario: package.json requires "^1.1.0", lock file locks at 1.0.0
npm ci      // Error: version mismatch
npm install // Installs 1.1.0 and rewrites lock file

Best Practices and Version Control Strategies

To ensure dependency stability, it is recommended to:

• Use exact versions in package.json (e.g., 2.1.6 instead of ^2.1.6), combined with the lock file for complete locking.
• Use npm install for updates in development environments, and npm ci for production or CI environments.
• Commit package-lock.json to version control systems to avoid version drift among team members.

For registries that do not support immutable packages (e.g., direct pulls from GitHub), the lock file may not fully guarantee consistency, requiring attention to environment configuration.

Conclusion

The rewriting of package-lock.json by npm install is an intentional design in npm 5.x and later, aiming to balance dependency locking with automatic updates. By understanding the priority mechanism of package.json, adopting the npm ci command, and using exact version declarations, developers can effectively manage project dependencies. This evolution reflects ongoing optimization of package management tools between flexibility and stability.