MENU
プログラムとツールの使い方を、実務目線で分かりやすく整理
  1. ホーム
  2. プログラム
  3. 「Module not found」の直し方：依存関係とパスを順に確認する基本

「Module not found」の直し方：依存関係とパスを順に確認する基本

プログラム
「Module not found」の直し方：依存関係とパスを順に確認する基本

「Module not found」が出たときに見る場所：依存関係とパスの確認手順

Module not found は、プログラムが「指定されたモジュールを見つけられない」ときに出るエラーです。Web制作やWordPress周辺のビルド作業では、Node.js の npm run build、Next.js や Vite の起動、PHPやPythonの補助スクリプト実行時によく遭遇します。

最初に見るべき場所は大きく2つです。依存関係が入っているか、そして import / require で指定したパスが実際のファイル位置と合っているか。この2点を順に確認すると、多くのケースは原因を切り分けられます。

この記事では Node.js の例を中心に、実務で使う確認手順、入力例、出力例、よくある失敗、代替手段を整理します。

  • 何ができるか：Module not found の原因を依存関係、ファイルパス、実行場所に分けて確認できる
  • 使う場面：WordPressテーマのビルド、フロントエンド開発、サーバー上の自動化スクリプト、CI実行時のエラー調査
  • 対象環境：Node.js / npm を使う一般的なプロジェクト。例は npm コマンドを中心に説明
  • 注意点：エラーメッセージの文言はツールによって少し違うが、確認する順番はほぼ同じ
目次

まずは「何が見つからないのか」を読む

Module not found は、エラー本文に不足している名前が出ます。そこを読まずに設定ファイルを触ると、遠回りになりがちです。

たとえば、次のようなエラーが出たとします。

Error: Cannot find module 'dotenv'
Require stack:
- /var/www/example/scripts/deploy.js

この場合、探す対象は dotenv です。deploy.js の中で dotenv を読み込もうとしたが、Node.js が見つけられなかった、という意味です。

一方、次のような表示なら少し違います。

Module not found: Error: Can't resolve './components/Header'

こちらは ./components/Header という相対パスの先に、期待したファイルが見つからない状態です。つまり、npmパッケージではなく、プロジェクト内のファイル名や配置を疑います。

ここがポイント: dotenv のような名前なら依存関係、./components/Header や ../lib/api のような書き方ならパスを先に確認します。

原因1：依存関係がインストールされていない

パッケージ名がエラーに出ている場合は、まず package.json と node_modules の状態を確認します。

Node.js では、外部パッケージを import や require で読み込む前に、npmなどでプロジェクトへ追加しておく必要があります。公式ドキュメントでも、npmはパッケージのインストールや依存関係管理に使うツールとして説明されています。

入力例

たとえば dotenv を使うコードがあるとします。

require('dotenv').config();

console.log(process.env.SITE_URL);

この状態で dotenv が入っていないと、実行時に Cannot find module 'dotenv' が出ます。

確認は次の順番で行います。

npm ls dotenv

入っていない場合、次のような出力になります。

example-project@1.0.0 /var/www/example
└── (empty)

対処法

通常の実行に必要なパッケージなら、次のように追加します。

npm install dotenv

ビルド時や開発時だけ使うツールなら --save-dev を付けます。

npm install --save-dev vite

ここで迷いやすいのは、dependencies と devDependencies の違いです。

  • dependencies：本番実行にも必要なもの
  • devDependencies：ビルド、テスト、型チェックなど開発時に使うもの
  • 例：dotenv は実行時に読むなら dependencies、vite や eslint は多くの場合 devDependencies

WordPressテーマのアセットをビルドするだけなら、ビルドツールは devDependencies に置かれることが多いです。ただし、サーバー上で npm install --omit=dev のように開発依存を除外していると、ビルドに必要なツールまで消えてエラーになります。

原因2：npm install した場所と実行場所が違う

依存関係が入っているのに見つからない場合、コマンドを実行しているディレクトリを確認します。

Node.js は、現在のファイルや実行位置を基準に node_modules を探します。プロジェクトの外側でコマンドを実行していると、正しい package.json や node_modules を見に行けません。

よくある場面

WordPress案件では、次のような構成がよくあります。

wordpress/
  wp-content/
    themes/
      my-theme/
        package.json
        src/
        node_modules/

この場合、npmコマンドは my-theme で実行する必要があります。

cd wp-content/themes/my-theme
npm install
npm run build

もしWordPressルートで実行していると、そこに package.json がない、または別の package.json を読んでしまうことがあります。

確認には pwd と ls が有効です。

pwd
ls package.json

期待する出力は、プロジェクトのディレクトリと package.json の存在です。

/var/www/example/wp-content/themes/my-theme
package.json

サーバーやCIでは、ローカルと作業ディレクトリが違うだけで同じエラーが出ます。GitHub Actions、レンタルサーバーのSSH、Dockerコンテナ内では、最初に「今どこで実行しているか」を見てください。

原因3：相対パスが実際のファイル位置とずれている

エラーに ./ や ../ が出ている場合は、依存関係より先にファイルパスを見ます。

相対パスは、読み込む側のファイルから見た位置で書きます。プロジェクト全体のルートから見た位置ではありません。

NG例

次の構成を考えます。

src/
  pages/
    index.js
  components/
    Header.js

src/pages/index.js から Header.js を読み込むなら、次のように書きます。

import Header from './components/Header';

これは間違いです。index.js から見ると、components は同じ階層ではなく、ひとつ上の src 配下にあります。

改善例

正しくは次のようになります。

import Header from '../components/Header';

.. は「ひとつ上の階層」を意味します。つまり、src/pages から src に戻り、そこから components/Header に進む、という指定です。

この考え方は、画像、CSS、JSONファイルを読み込む場合にも同じです。

import settings from '../config/settings.json';

パスで詰まったときは、頭の中だけでたどらず、ディレクトリ構造を書き出すと早く直せます。

原因4：ファイル名の大文字小文字が違う

ローカルでは動くのにサーバーで失敗する場合、ファイル名の大文字小文字を確認します。

たとえば、実際のファイル名が Header.js なのに、読み込み側で次のように書いているケースです。

import Header from '../components/header';

macOSやWindowsの設定によってはローカルで通ることがあります。しかしLinuxサーバーや多くのCI環境では、Header.js と header.js は別物として扱われます。

実務では、次のように表記をそろえるのが安全です。

  • コンポーネント：Header.js のように先頭大文字で統一する
  • 読み込み側：実ファイル名と完全に同じ大文字小文字で書く
  • Gitでリネームした場合：大文字小文字だけの変更が反映されているか確認する

特にWordPressテーマをLinuxサーバーへ配置する場合、ローカルでは見逃した表記違いが本番ビルドで出ることがあります。

原因5：ES Modules と CommonJS の書き方が混ざっている

最近のNode.jsでは、import を使う ES Modules と、require を使う CommonJS の両方が使われます。混在すると、見つからないエラーとは別に、読み込み形式のエラーが出ることがあります。

Node.js公式ドキュメントでは、package.json の type フィールドによって .js ファイルをどちらのモジュール形式として扱うかが変わると説明されています。

代表的な違い

形式読み込み例よく使う場面
CommonJSconst fs = require('node:fs');古いNode.jsスクリプト、既存の設定ファイル
ES Modulesimport fs from 'node:fs';新しめのフロントエンド開発、モダンなNode.jsプロジェクト

たとえば package.json に次の指定がある場合、.js はES Modulesとして扱われます。

{
  "type": "module"
}

この状態でCommonJS前提のコードや設定を混ぜると、別のエラーにつながります。

const path = require('node:path');

ES Modulesとして書くなら、次のようにします。

import path from 'node:path';

ただし、すべてを無理にES Modulesへ寄せる必要はありません。既存のWordPressテーマやビルド設定では CommonJS のまま動いているものも多くあります。大事なのは、プロジェクト内で形式を不用意に混ぜないことです。

実務で使う確認チェックリスト

原因を探すときは、下から順に設定を触るより、浅い確認から始めます。

1. エラーに出ている名前を見る

Error: Cannot find module 'sharp'

この場合は sharp というパッケージ名を確認します。

npm ls sharp

なければインストールします。

npm install sharp

2. 実行ディレクトリを見る

pwd
ls package.json

package.json がある場所で実行しているかを確認します。

3. 依存関係を入れ直す

node_modules が壊れている、ロックファイルと状態がずれている、CIでキャッシュが古いといった場合は、入れ直しで直ることがあります。

npm install

CIや再現性を重視する環境では、package-lock.json を使って依存関係を固定する npm ci が使われます。npm公式ドキュメントでは、npm ci はクリーンなインストールを行うコマンドとして説明されています。

npm ci

ただし npm ci は既存の node_modules を削除して入れ直します。ローカルで未整理の状態を残したい場合は、実行前に影響範囲を確認してください。

4. 相対パスをファイル位置からたどる

import config from './config/site.json';

このコードがあるファイルから見て、./config/site.json が本当に存在するかを確認します。

ls src/pages/config/site.json

存在しないなら、../config/site.json などに直す必要があります。

5. 大文字小文字をそろえる

ls src/components

出力が次のようなら、importも Header に合わせます。

Header.js
Footer.js

import Header from '../components/Header';

よくある失敗と直し方

Module not found は、慣れてくるとパターンで見分けられます。ここでは初心者がつまずきやすい例をまとめます。

npm install をグローバルで済ませている

次のように -g を付けて入れると、グローバル環境に入ります。

npm install -g vite

CLIとして直接使うには便利な場合がありますが、プロジェクトの package.json には記録されません。別のPC、サーバー、CIでは同じ状態を再現できません。

プロジェクトで使うなら、基本はプロジェクト内に追加します。

npm install --save-dev vite

package.json だけ更新して npm install していない

Gitで他の人の変更を取り込んだあと、package.json や package-lock.json が変わっているのに npm install をしていないと、手元の node_modules には新しいパッケージがありません。

npm install

CIなら次のように固定された依存関係で入れ直します。

npm ci

Dockerやサーバーの中でだけ失敗する

Dockerコンテナやサーバーでは、ローカルの node_modules がそのまま使われるとは限りません。

確認するポイントは次の3つです。

  • コンテナ内で npm install または npm ci が実行されているか
  • 作業ディレクトリが package.json のある場所になっているか
  • 本番用インストールで devDependencies を除外していないか

ビルドをサーバー内で行うなら、ビルドに必要なパッケージもその環境に入っている必要があります。

関連ツールと代替手段の使い分け

解決方法は npm だけではありません。プロジェクトの管理方法によって、使うコマンドは変わります。

ツール確認コマンド例向いている場面
npmnpm ls パッケージ名Node.js標準に近い構成、初心者向け、既存案件で広く使われる
Yarnyarn why パッケージ名Yarnで管理されている既存プロジェクト
pnpmpnpm why パッケージ名モノレポや依存関係を効率よく管理したいプロジェクト

ただし、同じプロジェクトで npm、Yarn、pnpm を混ぜると、ロックファイルが複数できて状態が分かりにくくなります。

  • npm：package-lock.json
  • Yarn：yarn.lock
  • pnpm：pnpm-lock.yaml

初心者が既存案件に入る場合は、まずリポジトリにあるロックファイルを見ます。package-lock.json があれば npm、yarn.lock があれば Yarn、pnpm-lock.yaml があれば pnpm を使う、という判断が基本です。

Pythonの ModuleNotFoundError でも考え方は同じ

Node.js以外でも、原因の見方は大きく変わりません。

Pythonでは、次のようなエラーが出ます。

ModuleNotFoundError: No module named 'requests'

この場合も、まず requests がインストールされているかを確認します。

python -m pip show requests

なければインストールします。

python -m pip install requests

ここで大事なのは、pip だけでなく python -m pip を使うことです。複数のPythonが入っている環境では、pip が別のPythonに紐づいている場合があります。Python公式ドキュメントでも、モジュールとして pip を実行する方法が案内されています。

仮想環境を使っているなら、有効化されているかも確認します。

python -V
python -m pip -V

Node.jsでもPythonでも、エラーの本質は同じです。今実行している環境から、そのモジュールが見えるかを確認します。

最後に見るべきポイント

Module not found は、複雑な設定ミスに見えても、実際には「入っていない」「場所が違う」「名前が違う」のどれかであることが多いエラーです。

迷ったら、次の順で確認してください。

  1. エラーに出た名前が、パッケージ名か相対パスかを見る
  2. package.json があるディレクトリで実行しているか確認する
  3. npm ls パッケージ名 で依存関係の有無を見る
  4. npm install または npm ci で依存関係を再現する
  5. 相対パスとファイル名の大文字小文字を実ファイルに合わせる
  6. ES Modules と CommonJS の混在がないか見る

次に見るべき分岐点は、ローカルだけで起きるのか、サーバーやCIだけで起きるのかです。ローカルだけなら依存関係や作業ディレクトリ、サーバーだけなら大文字小文字、devDependencies の除外、Docker内のインストール手順を重点的に確認すると、原因に近づきやすくなります。

参照リンク

プログラム
CLI Module not found Node.js npm Python エラー対処 パス 依存関係
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次