How to have `pnpm install` install everything exactly to the specs of the pnpm-lock file?

How to Install Dependencies Exactly as Specified in pnpm-lock.yaml

When working on software projects, ensuring consistency between builds is crucial. With tools like pnpm, you can lock dependency versions and reproduce builds reliably by leveraging the pnpm-lock.yaml file. This article explains how to achieve this using pnpm commands, especially for scenarios involving CI/CD pipelines or long-term project maintenance.

Why Use pnpm-lock.yaml for Reproducible Builds?

The pnpm-lock.yaml file captures the exact versions of dependencies installed during the last update or install process. By using this file, you can:

• Avoid unexpected updates to dependencies.
• Reproduce builds reliably across environments.
• Ensure your project remains consistent, even years later.

Steps to Install Dependencies Based on pnpm-lock.yaml

Here is how to make sure pnpm installs dependencies exactly as specified in the lockfile:

1. Use the --frozen-lockfile Option

The --frozen-lockfile flag ensures that pnpm will not modify the pnpm-lock.yaml file during the installation process. If the pnpm-lock.yaml file is not in sync with package.json, the installation will fail.

Run the following command:

pnpm install --frozen-lockfile

In CI/CD environments, this behavior is enabled by default. If the lockfile and package.json are mismatched, you will need to resolve the discrepancies before running the install.

2. Delete node_modules for a Fresh Start

If you want to ensure a completely fresh installation based on the lockfile, delete the node_modules folder before running the install command:

rm -rf node_modules
pnpm install --frozen-lockfile

This guarantees that the installation is performed from scratch, strictly following the versions in pnpm-lock.yaml.

3. Prevent Updates with Locked Versions

To ensure that dependencies remain consistent, avoid using version ranges (^ or ~) in your package.json. Instead, lock specific versions to ensure no changes occur over time.

For example, change this:

"dependencies": {
  "express": "^4.18.2"
}

To this:

"dependencies": {
  "express": "4.18.2"
}

4. Recreate pnpm-lock.yaml When Necessary

If you need to update dependencies or regenerate the lockfile, use:

pnpm install --lockfile-only

This updates the pnpm-lock.yaml without installing dependencies, allowing you to inspect changes before committing.

FAQs

What happens if the lockfile and package.json are out of sync?

If you run pnpm install --frozen-lockfile and the files are out of sync, the installation will fail. To fix this, either update package.json or synchronize the lockfile by running:

pnpm install --no-frozen-lockfile

Can I use pnpm to update dependencies?

Yes, use the pnpm update command to update dependencies to their latest compatible versions as specified in package.json. Always review the updated pnpm-lock.yaml to ensure compatibility.

How do I ensure long-term reproducibility?

• Commit the pnpm-lock.yaml file to your version control system.
• Use --frozen-lockfile in CI/CD pipelines to prevent unwanted changes.
• Avoid version ranges in package.json to lock exact versions.

Conclusion

By using pnpm install --frozen-lockfile and committing the pnpm-lock.yaml file, you can ensure consistent and reproducible builds. These practices are essential for maintaining software stability over time and reducing headaches caused by dependency updates.

For more information, check out the official pnpm documentation.