Cannot find module 오류 해결법, 파일 경로부터 npm 설치까지 체크리스트

Cannot find module 오류 해결법, 파일 경로부터 npm 설치까지 체크리스트

Node.js나 자바스크립트 프로젝트를 실행하다 Error: Cannot find module이라는 메시지를 만나면 모듈이 왜 갑자기 사라졌는지 당황하기 쉽습니다. 방금 설치한 패키지인데도 오류가 나거나, 내 컴퓨터에서는 되는데 다른 환경에서는 실행되지 않는 경우도 있는데요.
 
Cannot find module 오류는 말 그대로 실행 환경이 요청한 모듈이나 파일을 찾지 못했다는 의미입니다.
 
하지만 원인은 단순한 파일 경로 오타부터 npm 패키지 미설치, node_modules 문제, 실행 위치와 모듈 시스템 차이까지 다양합니다. 가장 빠르게 확인할 수 있는 순서대로 알아보겠습니다.
 
 

Cannot find module 뜻부터 확인하기

Node.js에서 require() 또는 모듈 로딩 과정에서 지정한 파일이나 패키지를 찾지 못하면 Cannot find module 오류가 나타날 수 있습니다.

const helper = require("./helper");

위 코드에서 실제 helper 파일이 존재하지 않거나 경로가 잘못됐다면 모듈을 불러올 수 없습니다. 외부 패키지를 사용하는 경우에도 설치되어 있지 않거나 현재 프로젝트에서 찾을 수 없다면 비슷한 문제가 발생할 수 있습니다.

 
따라서 이 오류를 만났을 때는 무작정 npm 명령부터 실행하지 말고 내가 만든 로컬 파일을 찾지 못한 것인지, 외부 npm 패키지를 찾지 못한 것인지 먼저 구분하는 것이 좋습니다.
 
 

Cannot find module 원인 1, 파일 경로 확인

직접 만든 파일을 import하거나 require했다면 가장 먼저 상대 경로를 확인하세요. 특히 현재 파일과 대상 파일의 위치를 착각하면서 ./와 ../를 잘못 사용하는 경우가 많습니다.

// 같은 폴더
const util = require("./util");
// 상위 폴더
const util = require("../util");

./는 현재 파일 기준의 경로를 나타내고 ../는 한 단계 위쪽을 의미합니다. 폴더 구조가 복잡하다면 에디터의 파일 탐색기에서 실제 위치를 확인한 뒤 경로를 다시 작성해 보세요.

 
 

파일명 대소문자와 확장자도 체크하세요

로컬에서는 정상인데 서버나 배포 환경에서만 Cannot find module이 발생한다면 파일명의 대소문자를 확인할 필요가 있습니다. 운영체제와 파일 시스템에 따라 대소문자를 다르게 처리할 수 있기 때문입니다.

// 실제 파일
UserService.js
// 코드
require("./userservice");

개발 환경에서는 우연히 동작하더라도 다른 환경에서는 찾지 못할 수 있습니다. 실제 파일명과 코드의 철자를 정확하게 일치시키는 것이 안전합니다.
 
ES Module을 직접 사용하는 환경에서는 상대 import 경로의 파일 확장자도 중요한 경우가 있습니다.

import { sum } from "./math.js";

 
따라서 CommonJS 예제를 ESM 프로젝트로 옮겼다면 단순히 require를 import로 바꾸는 것에서 끝내지 말고 경로 작성 방식까지 함께 확인하세요.
 
 

npm 패키지가 설치되지 않은 경우

외부 패키지를 불러오는 코드에서 오류가 발생했다면 해당 패키지가 현재 프로젝트에 실제로 설치되어 있는지 확인해야 합니다.

const express = require("express");

 
프로젝트에서 express를 사용하지만 설치하지 않았다면 모듈을 찾을 수 없습니다. 필요한 패키지는 프로젝트 폴더에서 npm을 이용해 설치할 수 있습니다.

npm install express

 

설치가 끝나면 package.json의 dependencies와 node_modules를 확인해 보세요. 패키지 이름의 철자가 잘못되지 않았는지도 함께 살펴보는 것이 좋습니다.

 
 

node_modules가 없다면 npm install 확인하기

Git 등에서 프로젝트를 새로 내려받은 뒤 바로 실행했을 때 Cannot find module이 나타나는 경우가 많습니다. 일반적으로 node_modules 폴더 자체를 저장소에 포함하지 않는 프로젝트가 많기 때문입니다.

 

이 경우 프로젝트의 package.json과 lock 파일을 기준으로 필요한 의존성을 설치해야 합니다.

npm install

 

프로젝트가 package-lock.json을 사용하고 재현 가능한 설치가 필요한 환경이라면 프로젝트 정책에 따라 npm ci를 사용하는 경우도 있습니다.

npm ci

 
중요한 점은 아무 폴더에서나 명령을 실행하는 것이 아니라 해당 프로젝트의 package.json이 있는 위치에서 실행하는 것입니다.
 
 

package.json dependencies 확인하기

패키지를 설치했다고 생각했는데 계속 찾지 못한다면 package.json을 확인해 보세요. 필요한 라이브러리가 dependencies 또는 프로젝트에서 사용하는 적절한 의존성 항목에 들어 있는지 살펴보는 것이 좋습니다.

{
  "dependencies": {
    "express": "설치된 버전"
  }
}

 
다른 사람에게 프로젝트를 전달하거나 배포할 때도 package.json과 lock 파일이 제대로 관리되고 있어야 필요한 모듈을 다시 설치하기 쉽습니다. 내 컴퓨터의 node_modules에만 우연히 존재하는 패키지에 의존하고 있지는 않은지 확인하세요.
 
 

잘못된 폴더에서 실행해도 문제가 생길까?

터미널의 현재 작업 폴더가 생각했던 위치와 다르면 설정 파일이나 실행 대상 경로를 잘못 참조하면서 문제가 생길 수 있습니다. 특히 여러 Node.js 프로젝트를 동시에 작업할 때 자주 발생합니다.
 

현재 터미널이 어느 프로젝트를 기준으로 실행되고 있는지 확인하고, package.json과 실행 파일이 예상한 프로젝트에 속해 있는지 살펴보세요. npm 패키지를 설치할 때도 같은 원칙이 적용됩니다.

 
 

Cannot find module 주요 원인 8가지

1. 상대 경로의 ./ 또는 ../를 잘못 작성한 경우
2. 파일명이나 폴더명에 오타가 있는 경우
3. 파일명의 대소문자가 실제 파일과 다른 경우
4. ESM 환경에서 필요한 파일 확장자를 빠뜨린 경우
5. npm 패키지를 아직 설치하지 않은 경우
6. 프로젝트의 node_modules가 준비되지 않은 경우
7. 잘못된 프로젝트 폴더에서 설치·실행한 경우
8. CommonJS와 ES Module 설정을 혼동한 경우

 
에러 메시지에는 찾지 못한 모듈의 이름이나 경로가 함께 표시되는 경우가 많습니다. 따라서 가장 먼저 어떤 모듈을 못 찾았다고 하는지 확인하면 점검 범위를 크게 줄일 수 있습니다.
 
 

node_modules를 삭제하고 다시 설치해야 할까?

Cannot find module을 검색하면 곧바로 node_modules를 삭제하고 다시 설치하라는 해결법을 자주 볼 수 있습니다. 의존성 설치가 손상됐거나 설치 상태가 꼬인 경우에는 도움이 될 수 있지만 모든 Cannot find module의 첫 번째 해결책은 아닙니다.
 
파일 경로 오타가 원인인데 node_modules를 여러 번 다시 설치해도 해결되지 않습니다. 먼저 에러 메시지에 표시된 대상이 로컬 파일인지 npm 패키지인지 확인하고, 실제 설치 여부와 경로를 점검한 뒤 재설치를 검토하는 편이 효율적입니다.
 
 

ES Module과 CommonJS 설정도 확인하세요

Node.js 프로젝트에서는 require()를 사용하는 CommonJS와 import를 사용하는 ES Module의 차이도 확인해야 합니다.

// CommonJS
const helper = require("./helper");

// ES Module
import helper from "./helper.js";

 

프로젝트의 package.json에 "type": "module"이 설정되어 있는지, 파일이 .mjs 또는 .cjs인지 등을 확인해 보세요. 모듈 시스템이 맞지 않는 경우에는 Cannot find module이 아닌 다른 import/require 관련 오류가 함께 나타날 수도 있습니다.

 
 

Cannot find module 해결 체크리스트

오류가 발생했다면 아래 순서대로 확인해 보세요. 처음부터 node_modules를 삭제하기보다 간단하고 가능성이 높은 원인부터 제거하는 것이 빠릅니다.
 

1단계	에러 메시지에서 찾지 못한 모듈 이름 확인
2단계	로컬 파일인지 npm 패키지인지 구분
3단계	파일 경로와 ./, ../ 확인
4단계	파일명·대소문자·확장자 확인
5단계	외부 패키지라면 설치 여부 확인
6단계	package.json과 node_modules 확인
7단계	현재 작업 폴더와 실행 위치 확인
8단계	ESM·CommonJS 설정 확인 후 필요 시 재설치

 
 

require is not defined와 무엇이 다를까?

앞서 살펴본 require is not defined와 Cannot find module은 비슷해 보이지만 의미가 다릅니다. require is not defined는 현재 실행 환경에 require 자체가 존재하지 않는 것이 핵심입니다.

 
반면 Cannot find module은 모듈을 불러오려는 과정은 시작됐지만 지정한 모듈이나 파일을 찾지 못한 상황을 의미합니다.
 
따라서 require is not defined라면 모듈 시스템을 먼저 확인하고, Cannot find module이라면 경로와 설치 상태를 우선 확인하는 것이 좋습니다.
 
 

Cannot find module 오류를 예방하려면?

파일과 폴더 이름의 규칙을 일관되게 관리하고 import 경로를 작성할 때 자동 완성 기능을 활용하면 단순한 오타를 줄일 수 있습니다. 외부 라이브러리를 추가했다면 package.json과 lock 파일도 함께 관리하는 습관을 들여보세요.
 
Cannot find module 오류가 나타났다면 가장 먼저 “로컬 파일을 못 찾은 것인가, npm 패키지를 못 찾은 것인가?”를 구분하는 것이 핵심입니다. 로컬 파일이라면 경로·파일명·확장자를, 패키지라면 설치 여부와 package.json, node_modules를 확인하세요.
 
무조건 npm install을 반복하거나 node_modules부터 삭제할 필요는 없습니다. 에러 메시지 확인 → 경로 확인 → 설치 확인 → 프로젝트 설정 확인 순서로 접근하면 대부분의 원인을 훨씬 빠르게 좁힐 수 있습니다.