pnpm - 高速パッケージマネージャー

pnpm（Performant npm）とは、Node.js のパッケージマネージャーです。npm や yarn と同じ役割を持ちますが、ハードリンクを使ったグローバルストア方式でパッケージを管理するため、インストール速度とディスク使用量の両面で優れた特性を持ちます。

対象読者: npm を使ったことがある JavaScript / Node.js 開発者の方

学習時間の目安: 読了 10分＋実践 10分

前提知識: Node.js・npm のインストール済み

npm との違い

npm は、プロジェクトごとに node_modules フォルダにパッケージをコピーします。10 のプロジェクトで react を使えば、10 か所にコピーが作られます。

pnpm は、ハードリンク（ファイルへの参照）を使って、同じパッケージをグローバルストア（一箇所）に 1 度だけ保存します。複数プロジェクトで同じパッケージを使っても、ディスク上の実体は 1 つです。

図で表すと次のようになります。

【npm の場合】
project-a/node_modules/react/  ← react のコピー（15MB）
project-b/node_modules/react/  ← react のコピー（15MB）
project-c/node_modules/react/  ← react のコピー（15MB）
合計: 45MB 消費

【pnpm の場合】
~/.pnpm-store/react/           ← react の実体（15MB）だけ
project-a/node_modules/react   ← 参照（ほぼ 0 バイト）
project-b/node_modules/react   ← 参照（ほぼ 0 バイト）
project-c/node_modules/react   ← 参照（ほぼ 0 バイト）
合計: 15MB のみ消費

特徴	npm	pnpm
導入	Node.js に同梱	別途インストールが必要
インストール速度	標準	高速（キャッシュ効率が高い）
ディスク使用量	プロジェクトごとにコピー	グローバルストアで大幅節約
依存関係の整合性	緩め（依存関係外パッケージも参照可能）	厳格（宣言したパッケージのみ参照可）
コマンドの互換性	—	npm とほぼ同じ

インストール方法

npm 経由（推奨）

Node.js と npm がインストール済みであれば、次のコマンドで pnpm をインストールできます。

npm install -g pnpm
pnpm --version          # バージョン確認

Corepack を使う方法（Node.js v16.9 以上）

Corepack とは、Node.js に同梱されているパッケージマネージャー管理ツールです。pnpm のバージョンをプロジェクト単位で管理できます。

corepack enable                          # Corepack を有効化
corepack prepare pnpm@latest --activate  # 最新の pnpm を有効化
pnpm --version                           # バージョン確認

nvm 環境での注意点

nvm を使っている場合、Node.js のバージョンを切り替えると、グローバルインストールした pnpm が使えなくなることがあります。nvm はバージョンごとにグローバルパッケージを分離して管理するためです。

解決策1: Corepack を使う

Corepack は nvm のバージョン切り替えに影響されずに動作します。Node.js を切り替えた後も pnpm コマンドが使えます。

解決策2: バージョン切り替え後に再インストールする

nvm use 22
npm install -g pnpm      # 切り替え後に再インストール

主なコマンド（npm との比較）

コマンドの構造は npm と似ているため、npm を使ったことがあれば違和感なく使えます。

操作	npm	pnpm
依存関係のインストール	`npm install`	`pnpm install`
パッケージの追加	`npm install <pkg>`	`pnpm add <pkg>`
開発依存の追加	`npm install -D <pkg>`	`pnpm add -D <pkg>`
スクリプトの実行	`npm run dev`	`pnpm run dev` または `pnpm dev`
パッケージの削除	`npm uninstall <pkg>`	`pnpm remove <pkg>`
グローバルインストール	`npm install -g <pkg>`	`pnpm add -g <pkg>`
一覧表示	`npm list`	`pnpm list`
更新確認	`npm outdated`	`pnpm outdated`

npm と pnpm はどちらを使うべきか

npm を選ぶ場面

JavaScript を始めたばかりのとき — Node.js と一緒にインストールされるため、追加設定なしにすぐ使えます
シンプルな個人プロジェクト — 数個のパッケージしか使わない場合、npm で十分です
チームが npm に慣れている — 既存のプロジェクトや、メンバー全員が npm を使っているチームでは、移行コストより安定性を優先するのが合理的です

pnpm を選ぶ場面

複数のプロジェクトを並行して管理している — グローバルストアにより、ディスク使用量と 2 回目以降のインストール時間を大幅に削減できます
CI/CD 環境のインストール時間を短縮したい — キャッシュが有効に機能し、テスト・ビルド時間の短縮に直結します
ディスク容量が少ない — 同じパッケージを複数プロジェクトで使う場合、pnpm なら実体は 1 つで済みます
モノレポ（複数パッケージを一つのリポジトリで管理する構成）を使う — pnpm はモノレポのワークスペース管理に優れています

移行の目安

npm でプロジェクトを始め、次のような状況になったら pnpm への移行を検討するタイミングです。

node_modules が大きくなりすぎてディスクを圧迫している
npm install の時間が長くなってきた
複数プロジェクトで同じライブラリを繰り返しインストールしている

移行手順は簡単です。package.json がある既存プロジェクトで pnpm install を実行するだけで動作します。

pnpm を使う場合の注意点

pnpm は依存関係の管理が npm より厳格です。package.json に明示的に記載されていないパッケージには、コード内からアクセスできません。これはバグの防止に役立ちますが、一部のライブラリで設定の調整が必要になる場合があります。

その場合は、プロジェクトルートに .npmrc ファイルを作成して設定を追加します。

# .npmrc（必要な場合のみ）
shamefully-hoist=true

この設定は pnpm の厳格な依存関係管理を緩和するため、必要最小限にとどめることを推奨します。

まとめ

pnpm は npm より高速でディスク効率が良いパッケージマネージャー
npm install -g pnpm でインストールできる
nvm 環境では Corepack を使うとバージョン切り替え時の問題を回避できる
コマンドの構造は npm と似ており、移行コストは低い
複数プロジェクトを管理する場合や、インストール速度を重視する場合に特に効果的

よくある質問

Q: npm がすでにあるのに pnpm も必要ですか？

A: 必須ではありませんが、インストール速度とディスク使用量の改善が見込めます。特に複数のプロジェクトを並行して進める場合や、ディスク容量が少ない環境では効果を実感しやすいです。

Q: pnpm を使うと既存の npm プロジェクトも動きますか？

A: package.json がある既存プロジェクトで pnpm install を実行するだけで動作します。ただし、package-lock.json（npm の管理ファイル）ではなく pnpm-lock.yaml が生成されます。

Q: yarn との違いは何ですか？

A: yarn も npm の代替パッケージマネージャーですが、pnpm はディスク効率（グローバルストア）と依存関係の厳格な管理が特徴です。機能面は近いため、プロジェクトの方針や既存の設定に合わせて選択してください。

Q: pnpm-lock.yaml を Git に含めるべきですか？

A: はい。pnpm-lock.yaml は package-lock.json と同様に、チーム全員が同じバージョンのパッケージを使えるようにするためのファイルです。必ず Git に含めてください。