npmのバージョン確認・更新のすべて｜Node環境お困り解決

npmのバージョンを確認したいとき、ターミナルやコマンドプロンプトで何を入力すればいいのか、ご存じですか？

答えは驚くほどシンプルです。たった1行のコマンド npm -v で、インストール済みのnpmバージョンが即座に表示されます。

しかし開発環境とサーバー環境でnpmのバージョンが異なると、パッケージのインストール失敗、予期しない動作の違いなど、原因究明が難しい問題が発生します。また、チーム開発では、メンバー間で環境がズレるだけで、同じコマンドが一人には成功して一人には失敗する、といった悪夢のような状況に陥ります。

本記事では、npm バージョン確認の基本から、エラー時の対処法、チーム開発での統一テクニック、CI/CD環境での自動化まで、実務で必ず役に立つ知識を網羅しました。初心者がつまずくポイントをすべてカバーしているため、これ1記事でnpmバージョン管理の全てが分かります。

npm バージョン確認の基本コマンド

このセクションでは、npm のバージョン確認にあたって必須の基本コマンドを、3つのパターンに分けて解説します。npm -v と npm --version の違い、正常な表示とエラーの見分け方、そして Node.js とのセット確認まで、最初に押さえておくべき知識をまとめました。

npm -v と npm –version の違いと正しい使い方

①コマンド

npm のバージョンを確認する最も基本的なコマンドは npm -v です。npm --version という長い形式も存在し、どちらの結果も完全に同じです。短縮形の npm -v が慣習的に使われるのは、タイプ数を減らし、スクリプトやドキュメントで可読性が高いからです。

大切な注意点として、npm version （ハイフンなし）は全く異なるコマンドです。こちらは現在のプロジェクトのバージョン番号を表示・更新するもので、package.json に記載されたバージョンを操作します。初心者が混同しやすい落とし穴なので、必ず区別してください。

②実行例（入力と出力）

# 入力例
npm -v

# 出力例
10.2.4

# ------------
# 別の方法
# ------------

# 入力例2
npm --version

# 出力例2
10.2.4

別コマンドの例（これは「プロジェクトのバージョン」を表示）：

# 入力例
npm version

# 出力例
{
  'npm-version-guide': '1.0.0',
  npm: '10.2.4',
  node: '18.17.0',
  v8: '10.2.286.23-node.51',
  uv: '1.44.2',
  zlib: '1.2.13.1-motley',
  brotli: '1.0.9',
  acores: '21.4.0',
  http_parser: '2.9.4',
  openssl: '3.0.7+quic',
  ares: '1.19.1',
  modules: '108',
  nghttp2: '1.51.0',
  napi: '9',
  llhttp: '8.1.0',
  ca_version: '3.85.0'
}

③補足・注意点

npm -v と npm version は何が違うのか：ハイフン付き（-v / --version）は npm 本体のバージョン、ハイフンなし（version）はプロジェクト情報全体を確認できます。

注意点：npm -v は現在のシェル（ターミナル）の PATH に登録されている npm を実行します。複数のバージョンをインストール済みの場合、どの npm が使われるかは環境次第なので注意が必要です。

正常なバージョン番号の表示とエラー画面の正確な見分け方

①結論・コマンド

npm -v を実行したとき、画面に数字だけが表示されていれば成功です。バージョン番号は「メジャー.マイナー.パッチ」の形式（例：10.2.4）で、セマンティックバージョニング（SemVer）という国際的な規則に従っています。

逆に「command not found」や「’npm’ は、内部コマンドまたは外部コマンド〜として認識されていません」といったメッセージが出た場合、npm がインストールされていないか、PATH（環境変数）に登録されていない状態です。この場合は次のセクションで解決策を説明します。

②実行例（入力と出力）

成功例：

npm -v

10.2.4

失敗例（macOS・Linux・WSL）：

npm -v

command not found: npm

失敗例（Windows PowerShell）：

npm -v

npm : 'npm' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

③つまずきポイント・補足

エラーメッセージの文言は OS（オペレーティングシステム）と使用シェルで異なります。Windows の PowerShell と Command Prompt (cmd.exe) でも違いますし、macOS のターミナルと WSL（Windows Subsystem for Linux）でも異なります。

「バージョンが表示される = npm が正常にインストール・セットアップされている」と判断できます。数字が小さく見えても（例：9.x.x）、プロジェクトの require する最低バージョンを満たしていれば問題ありません。ここで重要なのは「無いか有るか」「動くか動かないか」を判断することで、数字自体の大小ではないという点を覚えておきましょう。

互換性チェックに必須！Node.jsのバージョンもセットで確認

①結論・コマンド

npm の確認と同じくらい重要なのが、Node.js のバージョン確認です。npm と Node.js は常にセットで管理される関係にあります。npm は Node.js 本体に付属するパッケージマネージャーですので、Node.js のバージョンが決まると、そこに内含されている npm のバージョンもほぼ自動的に決まってしまいます。

チーム開発やプロジェクト引き継ぎで環境を揃えるときは、必ず両方のバージョンを確認し、公式の対応表を参照してください。Node.js 16.x には npm 8.x が付属、Node.js 18.x には npm 9.x が付属、といった具合です。

②実行例（入力と出力）

npm のバージョン確認：

npm -v

10.2.4

Node.js のバージョン確認：

node -v

v18.17.0

両方を一度に確認（npm 及び node のメジャーコンポーネント全て）：

npm version

{
  'sample-project': '1.0.0',
  npm: '10.2.4',
  node: '18.17.0',
  v8: '10.2.286.23-node.51',
  uv: '1.44.2',
  zlib: '1.2.13.1-motley',
  brotli: '1.0.9',
  acores: '21.4.0',
  http_parser: '2.9.4',
  openssl: '3.0.7+quic',
  ares: '1.19.1',
  modules: '108',
  nghttp2: '1.51.0',
  napi: '9',
  llhttp: '8.1.0',
  ca_version: '3.85.0'
}

③つまずきポイント・補足

実務でよく見かけるのは「npm は最新だけど Node.js が古い」「逆に Node.js は新しいのに npm をアップデートしていない」といった不一致です。特に Node.js をバージョン管理ツール（nvm や fnm）で切り替えている場合、npm も自動的に切り替わるのに気づかない人が多いです。

公式の Node.js リリースページ（https://nodejs.org/ja/about/previous-releases）では、各 Node.js バージョンに付属する npm バージョンが明記されています。新しいプロジェクトを始めるときや、チームのセットアップで悩んだときは、この対応表を確認するのが最も確実な解決策です。

さらに、GitHub Actions や CI/CD パイプラインを使う場合も、両方のバージョンを明示的に指定することが推奨されます。「ローカルでは動くのに CI で失敗した」というのは、ほぼ全てバージョン差異が原因です。

npmパッケージのバージョン確認・一覧表示方法

このセクションでは、npm でインストールされているパッケージのバージョンを確認する方法を解説します。プロジェクトローカルのパッケージ確認、グローバル環境の確認、特定ライブラリの全リリース履歴の調査、バージョン指定によるインストールまで、実務で頻繁に使うコマンドをカバーしています。

「npm list」でローカルプロジェクトのインストール済みパッケージ一覧を見る

①結論・コマンド

プロジェクトディレクトリにインストールされているパッケージとそのバージョンを一覧表示するには npm list を実行します。このコマンドは package.json と node_modules フォルダの内容を読み込み、ツリー構造で表示するため、依存関係の階層が一目で分かります。

npm list の結果に MISSING や INVALID といった警告が出る場合もあります。これは依存関係に不一致がある状態で、通常は npm install を再度実行することで解決します。

②実行例（入力と出力）

npm list

出力例（執筆時点）：

sample-project@1.0.0 /Users/developer/sample-project
├── express@4.18.2
├── axios@1.4.0
├── dotenv@16.3.1
├── nodemon@3.0.1
├── react@18.2.0
└── webpack@5.88.0
  ├── tapable@2.2.1
  ├── ajv@8.12.0
  ├── ejs@3.1.9
  └── terser@5.19.2
    └── source-map-support@0.5.21

トップレベルのパッケージのみを表示（依存パッケージを含めない）：

npm list --depth=0

出力例：

sample-project@1.0.0 /Users/developer/sample-project
├── express@4.18.2
├── axios@1.4.0
├── dotenv@16.3.1
├── nodemon@3.0.1
├── react@18.2.0
└── webpack@5.88.0

③つまずきポイント・補足

npm list で表示される依存関係は、場合によっては非常に深くなります。数百行に及ぶツリーが表示されることもあり、「自分がインストールしたパッケージがどれなのか分からない」という初心者の声が多いです。その場合は --depth=0 オプションを付けてトップレベルのみ表示するのが正解です。

もう1つ重要なポイントは、npm list は node_modules に存在するものをスキャンするという点です。そのため、package.json に記載されているのに node_modules に無い場合（例えば npm install 実行直後に node_modules を削除した場合）は MISSING と表示されます。

ローカルプロジェクトの node_modules に対してのみ実行されるので、グローバル環境のパッケージを確認する場合は次の H3 で説明する -g フラグが必要です。

グローバル環境のパッケージ一覧を確認する「npm list -g –depth=0」

①結論・コマンド

Node.js のシステム全体にグローバルインストールされたパッケージを確認するには npm list -g を使います。グローバル（グローバル＝PC全体で使える状態）にインストールされたパッケージには、CLI ツール（コマンドラインから直接実行できるプログラム）が多く含まれます。例えば create-react-app、typescript、yarn、gulp、eslint などです。

実務では npm list -g --depth=0 で、グローバルにインストールされたトップレベルのパッケージのみを表示することが最も役立ちます。理由は、グローバル環境の依存関係はローカルプロジェクトほど重要ではなく、「今どんなツールがシステムに入っているか」という大局的な把握が目的だからです。

②実行例（入力と出力）

npm list -g --depth=0

出力例（執筆時点）：

/usr/local/lib/node_modules
├── create-react-app@5.0.1
├── typescript@5.1.6
├── eslint@8.48.0
├── webpack@5.88.0
├── yarn@1.22.19
└── @angular/cli@16.2.0

プラットフォーム別の出力パス：

• macOS（Homebrew でインストール）：/usr/local/lib/node_modules
• macOS（nvm でインストール）：/Users/<ユーザー名>/.nvm/versions/node/v18.17.0/lib/node_modules
• Windows（デフォルトインストール）：C:\Users\<ユーザー名>\AppData\Roaming\npm\node_modules
• WSL（Ubuntu）：/usr/lib/node_modules または /home/<ユーザー名>/.local/lib/node_modules

③つまずきポイント・補足

グローバルインストールは 強力だが危険でもあります。システム全体に影響を与えるため、むやみに sudo npm install -g で強制インストールすることは推奨されません。特に macOS では sudo を常用すべきでない理由は、npm が root 権限で動作すると、後でパッケージの削除や更新がトラブルの原因になりやすいからです。

代わりに nvm（Node Version Manager）や fnm、Volta といったバージョン管理ツールを使うことで、sudo なしに安全にグローバルインストールができます。これらを使えば、ユーザーディレクトリ配下に Node.js 環境が隔離され、システムの安定性も保ちやすくなります。

「npm view versions」で特定ライブラリの最新版・過去リリース一覧を調べる

①結論・コマンド

特定のパッケージについて、これまでにリリースされたすべてのバージョンを確認するには npm view <パッケージ名> versions を使います。このコマンドは npm registry（インターネット上の公開パッケージ倉庫）にクエリを送り、そのパッケージのリリース履歴を取得します。

注意点として、npm view <パッケージ名> versions（複数形）と npm view <パッケージ名> version（単数形）は結果が異なります。複数形は全リリース一覧、単数形は最新版のバージョン番号だけです。用途に応じて使い分けが必要です。

②実行例（入力と出力）

複数形で全リリース一覧を取得：

npm view react versions

出力例（執筆時点、抜粋）：

[
  '0.3.0',
  '0.3.1',
  '0.3.2',
  ...（中略）...
  '18.2.0',
  '18.3.0',
  '18.3.1',
  '19.0.0-alpha.0',
  '19.0.0-alpha.1'
]

単数形で最新バージョンのみ取得：

npm view react version

出力例：

18.3.1

npm view で他の情報も同時に取得：

npm view react

出力例（一部抜粋）：

react@18.3.1 | MIT | deps: none | versions: 340 | updated: 8 days ago
=================================================================

name: react
version: 18.3.1
description: React is a JavaScript library for creating user interfaces with JSX
keywords:
  [ 'react', 'facebook', 'jsx', 'javascript', 'library' ]

dist-tags:
  latest: 18.3.1
  next: 19.0.0-alpha.1

maintainers:
  - luna <luna@fb.com>
  - sophiebits <sophiebits@fb.com>

repository: <https://github.com/facebook/react.git>
homepage: <https://github.com/facebook/react#readme>
bugs: <https://github.com/facebook/react/issues>

③つまずきポイント・補足

npm view <パッケージ名> versions の出力は、リリース数が多いパッケージでは配列形式で数百行に及ぶことがあります。grep や tail コマンドと組み合わせて、直近 10 件のみ表示するといった工夫が実務では役立ちます。

npm view react versions | tail -20

また、特定の範囲のバージョンを一覧したいときは --json フラグで JSON 形式で出力し、外部ツールで解析する手法もあります。

npm view react versions --json

さらに、パッケージに @latest、@next、@beta といった dist-tag（配布タグ）が付与されている場合、それらを指定してインストールすることで、自動的に特定の系統のバージョンを取得できます。例えば React の場合、@latest は安定版（18.3.1）を、@next は次期プレビュー版（19.0.0-alpha）を指します。

特定のバージョンを指定してインストールする「npm install @」の書き方

①結論・コマンド

プロジェクトに特定のバージョンのパッケージをインストールするには、npm install <パッケージ名>@<バージョン> という形式を使います。バージョン指定には複数の方法があり、確定的な指定（@4.2.1）、範囲指定（@^4.2.0 や @~4.2.0）、タグ指定（@latest や @next）が使えます。

パッケージをインストールすると同時に package.json にも自動的に記録されるため、team 開発では環境の統一に大変役立ちます。

②実行例（入力と出力）

確定的なバージョン指定でインストール：

npm install express@4.18.2

出力例：

added 50 packages, and audited 51 packages in 2s

6 packages are looking for funding
  run `npm fund` for details

package.json の dependencies に追加された内容：

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

最新版（@latest）を指定してインストール：

npm install axios@latest

出力例：

added 1 package, and audited 52 packages in 1s

6 packages are looking for funding
  run `npm fund` for details

セマンティックバージョニングによる範囲指定：

npm install lodash@^4.17.0

または

npm install lodash@~4.17.0

開発用（devDependencies）としてインストール：

npm install webpack@5.88.0 --save-dev

または短縮形：

npm install webpack@5.88.0 -D

③つまずきポイント・補足

バージョン指定の中で、^（キャレット）と ~（チルダ）の違いはセマンティックバージョニングの理解に不可欠です。

実務では、package.json に記録される時点で自動的に ^ が付くことがほとんどです。つまり npm install express@4.18.2 でも、package.json には "express": "^4.18.2" と保存されます。これはマイナーアップデートまでは自動で適用する設定で、セキュリティアップデートを素早く反映できるメリットがあります。

ただし、チーム開発やプロジェクトの重要度が高い場合は、package-lock.json（または npm-shrinkwrap.json）を併用して完全にバージョンをロックすることが推奨されます。これにより、全員が同じバージョンで開発できるようになります。

バージョン確認で「npm: command not found」等のエラーが出た時の解決策

ターミナルやコマンドプロンプトで npm -v を実行しても「コマンドが見つからない」と言われる場合、環境設定やインストール状況の問題が考えられます。このセクションでは、エラーの原因を特定し、環境別の具体的な解決策を紹介します。

PATH（環境変数）未設定や未インストールが原因となるケース

結論：npmが実行できない主な原因は、Node.jsがインストールされていないか、環境変数PATHにnpmの実行ファイルが登録されていないです。

npmはNode.js付属のパッケージマネージャーです。Node.js自体がインストールされていなければ、npmも存在しません。まずはNode.jsのインストール状況を確認しましょう。

node -v

実行例（正常な場合）

v18.16.1

もし「node: command not found」「`’node’ は、内部コマンドまたは外部コマンド〜として認識されていません」と表示される場合、Node.js自体がインストールされていません。公式サイト（https://nodejs.org/）から最新LTS版をダウンロードして、インストーラーを実行してください。

次に、Node.jsがインストール済みの場合でもnpmが見つからない場合があります。このとき環境変数PATH（パソコン全体で使えるコマンドの置き場所を記録したリスト）が正しく設定されていない可能性があります。

環境変数PATHの内容を確認するには、環境別に以下のコマンドを使い分けます。

macOS / WSL / Linux

echo $PATH

実行例

/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

Windows（PowerShell）

$env:PATH

実行例

C:\Program Files\nodejs;C:\Users\(ユーザー名)\AppData\Roaming\npm;C:\Windows\System32

PATHの中に「/usr/local/bin」「C:\Program Files\nodejs」といった、Node.jsをインストールしたディレクトリが含まれているか確認してください。含まれていない場合は、PATHを手動で追加する必要があります。

補足：Windowsのインストーラーを使えば、通常PATHは自動で追加されます。PATHの追加方法は環境変数の設定画面から行いますが、複雑なため、最初からNode.js公式インストーラーを使うことをお勧めします。環境変数の手動編集に自信がない場合は、Node.jsを一度アンインストールし、公式インストーラーで再インストールする方が確実です。

Windows（PowerShell）・macOS・WSL（Ubuntu）での特有の注意点と権限（sudo）

結論：各環境ごとにトラブルの原因と対処方法が異なります。特にmacOSで安全にnpmを使い続けるには、sudo に頼らず、バージョン管理ツール（nvm）を活用すべきです。

Windows（PowerShell / コマンドプロンプト）の場合

Windowsでは npm.cmd ファイルが実行中にロックされるため、通常の権限では npm install -g npm@latest が失敗することがあります。なお、かつて使われていた npm-windows-upgrade ツールは現在非推奨（メンテナンス停止）となっており、エラーの原因となるため使用しないでください。

Windows環境で安全に npm を更新するには、以下のいずれかの方法を行います。

方法1：Node.js 公式インストーラーで上書き更新（最も確実）

Node.js 公式サイト（https://nodejs.org/）から最新 LTS 版のインストーラー（.msi）をダウンロードし、そのまま実行して上書きインストールします。Node.js と同時に付属の npm も安全に最新化されます。

方法2：PowerShellを「管理者として実行」してコマンドを実行

PowerShell を「管理者として実行」で起動し、以下のコマンドを実行します。

npm install -g npm@latest

方法3：nvm-windows や fnm などのバージョン管理ツールを利用する

nvm-windows や fnm などのバージョン管理ツールを導入している場合は、Node.js のバージョンを更新することで、それに紐づく npm も自動的に最新版へ切り替わります。

macOS の場合

macOSでnpmコマンドが見つからない場合は、Homebrewでインストールした場合とNode.js公式インストーラーの場合で対処が異なります。

which npm

実行例（Homebrewの場合）

/opt/homebrew/bin/npm

実行例（公式インストーラーの場合）

/usr/local/bin/npm

どちらでもインストール済みなのにコマンドが見つからない場合は、シェル設定ファイル（.bash_profileや.zshrc）にPATHが記載されていない可能性があります。以下で確認・追加できます。

cat ~/.zshrc | grep PATH

記載がなければ、エディタで .zshrc（Zshを使っている場合）または .bash_profile（Bashの場合）を開き、以下を追加します。

export PATH="/opt/homebrew/bin:$PATH"

その後、変更を有効化するには以下を実行します。

source ~/.zshrc

⚠️ macOSで sudo npm を常用すべきでない理由

一部の解説サイトでは「インストール時に権限エラーが出たら sudo npm install -g を使え」と書かれていますが、これは推奨されません。理由は3つです。

1. グローバルパッケージのオーナーがrootになり、後で権限トラブルが増える：
   sudo を使うとインストール先ディレクトリの所有者がroot（管理者）になり、その後の更新・削除時に再び sudo が必要になります。
2. セキュリティリスク：
   外部パッケージに管理者権限を与えることは、悪意あるパッケージ実行時のリスクを高めます。
3. ローカル開発環境として不自然：
   本来、開発環境は一般ユーザー権限で動作するべきです。

代替方法：nvmを使ってNode.jsとnpmを管理することが最善です。nvmはNode.jsをユーザーディレクトリに隔離インストールするため、管理者権限は不要です。以下で簡単にセットアップできます。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

その後、Node.jsをインストールするだけで、npmも自動的に権限問題なく使えます。

nvm install 18

WSL（Ubuntu）の場合

WSL環境でも基本的にはmacOSと同じく、sudo apt や apt-get によるシステムへの直接インストールは推奨されません。システム領域へインストールすると、グローバルパッケージインストール時に管理者権限が必要となり、トラブル（EACCES 権限エラー）の原因になります。

WSL（Ubuntu）に独立して Node.js を導入する際も、macOS と同様に nvm（Node Version Manager）を使ってユーザーディレクトリ配下にインストールするのが最善の手法です。

# nvmのインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# シェル設定の反映（またはターミナルの再起動）
source ~/.bashrc

# Node.js LTS版のインストール
nvm install --lts

インストール後、権限（sudo）を必要とせずに安全に確認・利用できます。

npm -v

10.2.4

あわせて読みたい

【初心者OK】npm audit fixとは？エラーの意味・--forceの使い方・解決しないときの対処法まで徹底解説

npm audit fixの基本から応用までを丁寧に解説する完全ガイド。脆弱性チェックの仕組みや自動修正の方法、--forceによる強制更新のリスク、よくあるエラーとその対処法を具体例付きで紹介します。さらにYarnユーザー向けの代替手段や、パッケージ更新前後の影響確認方法等も詳しく解説しています。

watashi.xyz

2025.04.21

VS Codeの統合ターミナルで実行エラーや「認識されない」と表示される場合の対処

結論：VS Codeの統合ターミナルでnpmが認識されない場合は、ターミナルまたはVS Code自体を再起動し、PATHを読み直す必要があります。

VS Codeの統合ターミナルで npm -v を実行して「npm: command not found」と表示される場合、Node.jsはインストール済みでも、ターミナルプロセスが起動時に環境変数を読み込んでいない状態です。

対処方法1：統合ターミナルの再起動

VS Code内のターミナルウィンドウ右上にあるゴミ箱アイコンをクリックして、ターミナルプロセスを終了します。その後、新しくターミナルを開きます。

npm -v

これで認識される場合が多いです。

対処方法2：VS Code自体を再起動

統合ターミナルの再起動で解決しない場合は、VS Code自体を完全に閉じ、再度開いてください。VS Codeの再起動時に、全てのシェル環境変数が再読み込みされます。

対処方法3：統合ターミナルのシェルを確認・変更

VS Codeが使用しているシェル（bash, zsh, PowerShell等）が、正しいPATH設定を持つシェルでない場合があります。確認・変更するには、VS Code左下の歯車アイコン → 「設定」を開き、「Terminal」で検索します。

「Terminal › Integrated › Default Profile」という項目で、デフォルトシェルを指定できます。Windows環境では「PowerShell」、macOS / WSLでは「zsh」を選択することをお勧めします。

シェルを変更した後は、VS Code自体を再起動してください。

実行例：Windows（PowerShellに変更した場合）

1. VS Code設定で「Default Profile」を「PowerShell」に設定
2. VS Codeを再起動
3. 統合ターミナルを新規に開く

npm -v

実行例

9.6.7

補足：複数のNode.jsバージョンを管理している場合（nvm利用等）、シェル側のnvm初期化スクリプトが実行されていないこともあります。この場合は、.zshrcや.bash_profileに以下が記載されているか確認してください。

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

記載がなければ追加し、VS Codeを再起動します。

npm本体のアップデート・ダウングレード・バージョン切り替え手順

npm自体も定期的にアップデートがリリースされます。新機能の利用、セキュリティ脆弱性の修正、パフォーマンス改善を目的に更新することが一般的です。このセクションでは、最新版への更新、特定バージョンへのダウングレード、バージョン管理ツール利用時の挙動を説明します。

今のバージョンは古い？最新版へ確実かつ安全に更新する「npm install -g npm@latest」

結論：npm自体を最新版に更新するには、npm install -g npm@latest を実行します。ただしWindows環境では特殊な制約があるため、代替方法の使用を推奨します。

まず現在のバージョンを確認します。

npm -v

実行例

9.6.7

「古い」と判定する基準は、公式リリースノート（https://github.com/npm/npm/releases）と現在のバージョンを比較することです。執筆時点では npm 10系がLTS版です。バージョン番号の意味は次の通りです。

macOS / WSL（Ubuntu）の場合

npm install -g npm@latest

実行例（実行中のログ）

changed 30 packages, and audited 31 packages in 5s

実行例（更新後の確認）

npm -v

10.2.4

Windows（PowerShell）の場合

Windowsでは npm.cmd が OS による実行中のロック状態になるため、npm install -g npm@latest が失敗する場合があります。代わりに npm-windows-upgrade ツールを使用することをお勧めします。

npm install -g npm-windows-upgrade
npm-windows-upgrade

実行例

This utility will upgrade npm in your Node.js installation.
Downloading npm version 10.2.4
Installed npm version 10.2.4

コマンドプロンプトを使用している場合は、管理者権限で実行し、以下を試してみます。

npm install -g npm@latest

失敗した場合は npm-windows-upgrade の使用に切り替えてください。

⚠️ 更新時の注意点

1. 更新前に package-lock.json をバックアップしておく：
   万が一トラブルが発生した場合、ロールバックできるようにします。
2. 更新後は動作確認を必ず実施：
   プロジェクトで npm install を実行し、依存関係のインストールに問題がないか確認してください。
3. Node.jsバージョンとの互換性：
   npm と Node.js はバージョンペアで管理されています。例えば Node.js 14 には npm 6系が付属しています。古い Node.js を使用している場合、最新の npm 10系は動作しない可能性があります。以下で互換性を確認できます。

npm view npm versions

実行すると全バージョン一覧が表示されます。Node.js バージョンに対応する npm を公式ドキュメント（https://nodejs.org/）で確認し、該当バージョンをインストールしてください。

プロジェクトの要件に合わせて特定の古いバージョンへダウングレードする

結論：特定のバージョンに切り替えるには、npm install -g npm@X.Y.Z の形式で明示的にバージョンを指定します。

チーム開発において、全メンバーが同じ npm バージョンを使うことが重要な場合があります。例えば、レガシープロジェクトでは npm 8系が必須、といった制約です。この場合、ダウングレードが必要になります。

npm 8系にダウングレードする例

npm install -g npm@8

実行例

changed 5 packages, and audited 6 packages in 3s

特定のパッチバージョンを指定することも可能です。

npm install -g npm@8.19.4

実行例

npm -v

8.19.4

ダウングレード後は、必ず動作確認を実施してください。

npm install

プロジェクトのパッケージがダウングレード後のnpmで正常にインストールできるか、依存関係に警告が出ないか確認します。

補足：特定プロジェクトのみで古い npm を使いたい場合は、ダウングレードではなく npx npm@8 install を使う方法もあります。この場合、グローバルの npm バージョンを変えず、一時的に指定バージョンの npm コマンドを実行します。チーム全体でバージョンを統一する必要がない場合は、こちらが便利です。

npx npm@8 list

このコマンドは、ローカルプロジェクトで npm 8系を使ってパッケージ一覧を表示します。グローバル環境の npm には影響しません。

nvmやfnm、VoltaでNode.jsを切り替えた際のnpmバージョンの連動仕様

結論：nvm（Node Version Manager）、fnm（Fast Node Manager）、Volta などのバージョン管理ツールを使用する場合、Node.js のバージョンを切り替えると、npm も自動的に切り替わります。バージョンごとに独立した npm が紐付いているため、別途 npm の切り替え操作は不要です。

nvm を使用している場合の例を見てみましょう。

Node.js 16系をアクティブにしている状態

nvm use 16
node -v
npm -v

実行例

Now using node v16.20.2 (npm v8.19.4)
v16.20.2
8.19.4

Node.js 18系に切り替えた場合

nvm use 18
npm -v

実行例

Now using node v18.18.1 (npm v9.8.1)
v18.18.1
9.8.1

同じマシン上で異なるプロジェクトを複数管理している場合、プロジェクトごとに要求される Node.js バージョンが異なります。例えば、古いレガシープロジェクトは Node 14 が必須、新規プロジェクトは Node 18、といった具合です。

nvm を使えば、プロジェクトディレクトリに .nvmrc ファイルを配置することで、ディレクトリごとに自動切り替えが可能です。

.nvmrc ファイルの例

16.20.2

このファイルがディレクトリに存在する場合、nvm use を実行するだけでそのプロジェクト向けのバージョンが自動選択されます。

nvm use

実行例

Found /path/to/project/.nvmrc
Now using node v16.20.2 (npm v8.19.4)

fnm や Volta でも同じ仕様です

fnm（Fast Node Manager）や Volta を使用している場合も、Node.js バージョン切り替え時に npm が自動的に連動します。

fnm の場合：

fnm use 18
npm -v

Volta の場合：

volta install node@18
npm -v

どのツールでも、バージョン管理ツール経由で Node.js を切り替えた時点で、自動的に該当バージョンの npm が有効化されます。

⚠️ グローバルパッケージインストール時の注意点

nvm / fnm / Volta を使用している場合、グローバルパッケージ（npm install -g）を複数の Node.js バージョンでインストールすると、バージョンごとに別々のパッケージが保存されます。例えば、Node 16 でインストールしたグローバルパッケージは、Node 18 に切り替えた後は参照できません。

nvm use 16
npm install -g some-package
nvm use 18
npm list -g --depth=0

実行例（Node 18では some-package は表示されない）

/path/to/node/18/lib
`-- (some-package は存在しない)

グローバルパッケージを複数バージョン間で共有したい場合は、nvm の --default オプションやプロジェクトローカルインストール（npm install some-package）の利用を検討してください。

チーム開発やCI/CD環境でnpmのバージョン差異トラブルを防ぐ実践テクニック

複数人のチーム開発やCI/CDパイプライン（自動テスト・デプロイ環境）では、ローカル環境とサーバー環境のnpm・Node.jsバージョンが異なるために、「ローカルでは動くのに本番環境でエラーになる」という問題が頻出します。このセクションでは、バージョン差異を完全に防ぐ実践的なテクニックを紹介します。

package.jsonの「engines」指定とローカル環境を完全に一致させる方法

結論：package.jsonの engines フィールドでNode.js・npmのバージョン要件を明記し、.nvmrcと組み合わせることで、チーム全体と本番環境の統一を実現できます。

package.jsonは、プロジェクトのメタデータとパッケージ依存関係を管理するファイルです。このファイルに engines フィールドを追加することで、プロジェクトが要求するNode.jsとnpmのバージョンを明示します。

package.json の engines フィールド例

{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": "18.16.0",
    "npm": "9.5.0"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

このファイルをリポジトリに保存しておくと、チームメンバーが npm install を実行する際、npmがバージョン要件をチェックします。バージョンが一致しない場合、警告が出力されます。

実行例（バージョン不一致時）

npm install

npm WARN engine my-project@1.0.0: The engine "node" is incompatible with this package. Expected version "18.16.0" but got "16.20.0".
npm WARN engine my-project@1.0.0: The engine "npm" is incompatible with this package. Expected version "9.5.0" but got "8.19.4".

警告は出ますが、デフォルトではインストールが進行します。より厳密に強制するには、.npmrc ファイルで engine-strict=true を設定します。

.npmrc ファイル（プロジェクトルートに配置）

engine-strict=true

この設定が有効な場合、バージョン不一致でインストールが中止されます。

実行例（インストール失敗）

npm install

npm ERR! code ENOTSUP
npm ERR! notsup Unsupported platform for my-project@1.0.0: wanted {"node":"18.16.0","npm":"9.5.0"} (current: {"node":"16.20.0","npm":"8.19.4"})

ローカル環境で正しいバージョンに切り替える方法

nvmを使用している場合、プロジェクトルートに .nvmrc ファイルを配置します。

.nvmrc（Nodeバージョンのみ指定）

18.16.0

.nvmrc が存在するディレクトリで nvm use を実行すると、自動的に指定バージョンのNode.js（と付属のnpm）が有効化されます。

cd /path/to/project
nvm use

実行例

Found /path/to/project/.nvmrc
Now using node v18.16.0 (npm v9.5.0)

その後、npm install でパッケージをインストールします。

npm install

補足：fnmやVoltaを使用している場合も同様です。fnmは .nvmrc をサポートしており、Voltaは package.json の volta フィールドで管理します。

Volta での例

{
  "volta": {
    "node": "18.16.0",
    "npm": "9.5.0"
  }
}

「npm outdated」を使った古いパッケージの特定とセマンティックバージョニング（SemVer）の基礎

結論：npm outdated コマンドで更新可能なパッケージを一覧表示できます。セマンティックバージョニング（SemVer）の ^ と ~ の違いを理解することで、意図しないバージョン上昇を防げます。

インストール済みパッケージの中に、より新しいバージョンが利用可能なものがあるか確認するコマンドが npm outdated です。

npm outdated

実行例

Package      Current   Wanted   Latest   Location             Depended by
express      4.17.1    4.18.2   4.18.2   node_modules/express my-project
lodash       4.17.21   4.17.21  4.17.21  node_modules/lodash  my-project

表の意味は次の通りです。

このテーブルを見ると、express は「Current: 4.17.1」ですが「Wanted: 4.18.2」が利用可能であることが分かります。ここで重要なのが、package.jsonでどのようなバージョン指定をしているか、という点です。

SemVer（セマンティックバージョニング）の基礎

パッケージバージョンは通常 X.Y.Z の形式です。

例えば express 4.17.1 の場合、メジャー=4、マイナー=17、パッチ=1 です。

package.json での指定記法

package.json に依存パッケージを記載する際、バージョン番号の前に ^ または ~ が付きます。これらは「自動更新の許可範囲」を指定します。

{
  "dependencies": {
    "express": "^4.17.1",
    "lodash": "~4.17.21"
  }
}

npm outdated で「Wanted」の方が「Current」より大きい場合、その差分がアップデート可能な範囲です。

アップデートの実行

安全にアップデートするには npm update を使用します。これは package.json の指定範囲内（^ や ~ で許可された範囲）の最新バージョンをインストールします。

npm update

実行例（ログ出力）

changed 5 packages, and audited 15 packages in 3s

メジャーバージョンをアップデートしたい場合（例：express 4 → 5）は、明示的にバージョンを指定して npm install します。

npm install express@5

補足：package-lock.json の役割

npm install または npm ci を実行するたびに、package-lock.json（またはpackage-lock.json）が自動生成・更新されます。このファイルには、実際にインストールされたパッケージの正確なバージョンが記録されます。チーム開発では、このlockfileをリポジトリにコミットすることで、全メンバーが完全に同じバージョンのパッケージをインストールできます。lockfileがない場合、メンバーAと メンバーBでマイナー・パッチバージョンが異なり、開発環境がズレる可能性があります。

GitHub Actions等を使った自動化・CI/CDパイプラインへのバージョン確認ステップ組み込み

結論：GitHub ActionsのSetup Nodeアクションを使用し、CI/CDパイプラインで指定バージョンのNode.js・npmを固定することで、本番環境との差異を根絶できます。

CI/CD環境（GitHub Actions、GitLab CI、Jenkins等）では、自動テスト・ビルド・デプロイ時のNode.jsとnpmバージョンを厳密に管理する必要があります。ローカル開発環境とCI環境でバージョンが異なると、「ローカルでは成功したテストがCI環境で失敗する」といった問題が発生します。

GitHub Actions での例（Node.js 18.16.0、npm 9.5.0 を固定）

.github/workflows/ci.yml ファイルをリポジトリに配置します。

name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18.16.0'
          npm-version: '9.5.0'

      - name: Verify versions
        run: |
          node -v
          npm -v

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

このワークフローの重要ポイントを説明します。

1. Setup Nodeアクション

- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.16.0'
    npm-version: '9.5.0'

このステップで、CI環境のNode.jsとnpmを指定バージョンに固定します。node-version と npm-version は、package.json の engines フィールドと同じバージョンを記載してください。

2. npm ci の使用

- name: Install dependencies
  run: npm ci

npm ci（Clean Install）は、package-lock.json に記録された正確なバージョンをインストールするコマンドです。一方、npm install はpackage.json の指定範囲内で最新を検索するため、lockfileがあっても若干のバージョンズレが生じる可能性があります。CI環境では必ず npm ci を使用してください。

3. バージョン確認ステップ

- name: Verify versions
  run: |
    node -v
    npm -v

実際にセットアップされたバージョンをログに出力し、想定と異なる場合は即座に検出できるようにします。

実行例（ワークフロー実行時のログ出力）

Run node -v
v18.16.0

Run npm -v
9.5.0

マトリックスを使った複数バージョンのテスト

複数のNode.jsバージョンをテストしたい場合（例：Node 16、18、20で全て正常に動作するか確認）は、strategy.matrix を使用します。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ['16.20.0', '18.16.0', '20.3.0']

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

このワークフローは、3つのNode.jsバージョンそれぞれに対してテストを実行します。いずれかのバージョンでテスト失敗した場合は、そのバージョンでの問題を特定できます。

.gitignore での lockfile 管理

lockfileはリポジトリにコミットし、node_modules/ ディレクトリは .gitignore に記載して除外することが慣例です。

.gitignore

node_modules/
npm-debug.log

package-lock.json は必ずコミットしてください。これにより、CI環境もローカルも同じバージョンで動作が保証されます。

補足：GitLab CI や Jenkins でも同様の仕組みを実装できます。GitLab CI の場合は image フィールドで Node.js ベースイメージを指定し、Jenkins の場合は NodeJS Plugin を用いてバージョン指定します。

よくある質問（FAQ）

まとめ

npm のバージョン確認は、たった1行のコマンド npm -v で実行できます。しかし、エラーが出たときの対処、チーム開発でのバージョン統一、CI/CD環境でのトラブル防止まで視野に入れると、単なる確認操作ではなく、開発環境全体の品質を左右する重要なスキルになります。

すぐに実践できることから始める

1. npm -v でバージョンを確認し、node -v でNode.jsバージョンも合わせて確認する習慣をつける
2. エラーが出た場合は、環境変数PATH、インストール状況、ターミナル再起動を順に確認する
3. プロジェクトの package.json に engines フィールドを記載し、チーム間で要求バージョンを明示する

チーム開発に向けて準備する

1. .nvmrc または .node-version ファイルを使い、全メンバーが同じNode.js・npmバージョンで開発する
2. npm ci でlockfileベースのインストールを実行し、環境ズレを根絶する
3. GitHub Actions等のCI/CDパイプラインで、バージョン固定と自動検証を組み込む

継続的にスキルを深める

セマンティックバージョニング（SemVer）の ^ と ~ の違いを理解することで、パッケージ更新の意思決定がより正確になります。また、nvm や fnm などのバージョン管理ツールを導入すれば、複数プロジェクト間でのバージョン切り替えが一瞬で完了し、開発効率が飛躍的に向上します。

npm のバージョン管理は、初心者にとっては単なる「確認作業」に見えるかもしれません。しかし、実務では「環境差異によるバグ」「本番環境でのみ発生する問題」といった深刻なトラブルの多くが、バージョン不統一が原因です。この記事を土台に、チーム開発の現場で即座に活かしていただきたいと思います。

あわせて読みたい

npm自体を安全かつ確実に最新バージョンへアップデートする完全ガイド｜トラブル対策付

npmの動作が不安定だったり、新機能を使いたいときは「npm自体のアップデート」が重要です。npmを最新バージョンへ安全にアップデートする方法を、Windows・macOS・Linux別にわかりやすく解説します。バージョン確認コマンドや更新手順、トラブル対処法、チームでのnpm管理方法までまとめました。

watashi.xyz

2025.09.07