Module not found 에러가 계속 뜬다면? 해결법 총정리

Module not found 에러가 계속 뜬다면? 해결법 총정리

React, Next.js, Vite, Webpack 같은 프로젝트를 실행하다 보면 Module not found 오류를 자주 만나게 됩니다. 분명 파일도 있고 npm install까지 했는데 계속 같은 오류가 나타나면 무엇을 더 확인해야 할지 답답할 수 있는데요.
 
Module not found 오류의 핵심은 현재 빌드 도구나 실행 환경이 코드에서 요청한 파일 또는 패키지의 위치를 찾지 못한다는 것입니다.
 
단순 설치 문제뿐 아니라 상대 경로, 대소문자, alias, package.json, 실행 위치 등이 원인이 될 수 있습니다. 가장 쉬운 확인 방법부터 알아보겠습니다.
 
 

Module not found 오류 뜻부터 확인하기

예를 들어 다음처럼 다른 파일을 import했다고 가정해 보겠습니다.

import Header from "./components/Header";

 
현재 프로젝트에서 해당 경로에 파일이 없거나 빌드 도구가 이 경로를 정상적으로 해석하지 못하면 Module not found와 관련된 오류가 나타날 수 있습니다.
 
따라서 오류 메시지를 발견하면 가장 먼저 어떤 모듈 또는 경로를 찾지 못했다고 하는지 확인하세요. 에러 메시지에 표시된 대상이 내가 만든 파일인지 npm 패키지인지에 따라 해결 방향이 달라집니다.
 
 

Module not found 원인 1, 상대 경로가 틀린 경우

가장 흔한 원인은 역시 파일 경로입니다. 폴더 구조가 깊어지면 ./와 ../를 혼동하기 쉽습니다.

// 현재 폴더 아래 components
import Header from "./components/Header";
// 한 단계 위의 components
import Header from "../components/Header";

 
코드를 작성한 파일을 기준으로 대상 파일이 실제 어디에 있는지 다시 확인하세요. 에디터의 자동 완성 기능을 이용하면 직접 경로를 입력할 때 생기는 오타를 줄이는 데 도움이 됩니다.
 
 

파일명 대소문자 때문에 계속 발생할 수 있어요

파일은 존재하는데 Module not found가 계속 발생한다면 대소문자 차이도 확인해 보세요.

// 실제 파일
Header.jsx
// 잘못된 예
import Header from "./components/header";

 

개발 환경에서는 발견하지 못했던 문제가 다른 운영체제나 배포 서버에서 나타나는 경우가 있습니다. 파일명이 Header라면 import 경로도 같은 대소문자를 사용하는 습관을 들이는 것이 좋습니다.

 
만약 로컬에서는 되는데 배포 후 Module not found가 발생한다면 파일명과 import문의 대소문자를 우선 점검해 보세요.
 
 

npm 설치했는데 Module not found가 뜨는 이유

외부 라이브러리에서 문제가 발생했다면 해당 패키지가 현재 프로젝트에 설치되어 있는지 확인해야 합니다.

import axios from "axios";

 
axios가 설치되지 않았다면 현재 프로젝트 폴더에서 필요한 패키지를 설치합니다.

npm install axios

 
그런데 이미 설치했다고 생각하는데도 오류가 계속된다면 다른 폴더에서 npm install을 실행한 것은 아닌지 확인해 보세요. 여러 프로젝트를 동시에 작업하면 상위 폴더나 전혀 다른 프로젝트에 패키지를 설치하는 실수가 의외로 자주 발생합니다.
 
 

package.json과 node_modules 확인하기

Git에서 프로젝트를 새로 내려받았다면 node_modules가 없는 것이 일반적일 수 있습니다. 프로젝트에 필요한 패키지는 package.json과 lock 파일을 기준으로 다시 설치해야 합니다.

npm install

 
설치 후에도 문제가 계속된다면 package.json에 필요한 의존성이 존재하는지, 현재 터미널이 올바른 프로젝트 폴더에 있는지 확인하세요.
 
무조건 node_modules부터 삭제하고 다시 설치하는 것보다는 오류가 특정 패키지 하나에서 발생하는지, 여러 패키지가 동시에 사라졌다고 나오는지 먼저 살펴보는 편이 원인을 찾기 쉽습니다.
 
 

경로 alias 설정도 놓치기 쉬워요

프로젝트에서는 긴 상대 경로 대신 alias를 사용하는 경우가 있습니다.

import Button from "@/components/Button";

 

이 코드는 보기에는 깔끔하지만 @가 어떤 폴더를 의미하는지 빌드 도구나 프로젝트 설정에서 제대로 정의되어 있어야 합니다. 설정을 다른 프로젝트에서 복사했거나 관련 설정 파일을 수정했다면 alias가 정상적으로 연결되는지 확인하세요.

 
TypeScript나 특정 프레임워크에서는 경로 관련 설정이 여러 도구에 영향을 받을 수 있습니다. 에디터에서는 파일을 찾는데 실제 빌드에서는 찾지 못한다면 alias와 빌드 설정을 함께 살펴보는 것이 좋습니다.
 
 

파일을 이동하거나 이름을 바꾼 뒤 발생했다면?

컴포넌트나 유틸 파일을 다른 폴더로 이동했는데 기존 import문을 수정하지 않으면 Module not found가 발생합니다. 파일 이름을 변경했을 때도 마찬가지입니다.

// 이전 위치
import Card from "./components/Card";
// 파일 이동 후 실제 위치가 달라졌다면
import Card from "./ui/Card";

 
프로젝트 전체 검색을 이용해 이전 경로를 사용하는 import문이 남아 있는지 확인해 보세요. 하나의 파일을 여러 곳에서 import하고 있었다면 일부 코드만 수정해 오류가 계속되는 경우도 있습니다.
 
 

확장자와 모듈 해석 방식도 확인하세요

환경에 따라 import 경로의 확장자를 자동으로 처리하는 범위가 다를 수 있습니다. 특히 Node.js의 ES Module을 직접 사용하거나 빌드 설정을 변경했다면 파일 경로 작성 규칙을 확인할 필요가 있습니다.

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

 

또한 실제 파일은 .js, .jsx, .ts, .tsx 중 하나인데 설정에서 해당 확장자를 예상대로 처리하지 못하는 상황도 점검해야 합니다. 다른 프로젝트에서 정상 동작했던 import문이 현재 환경에서도 반드시 똑같이 동작한다고 생각하지 않는 것이 좋습니다.

 
 

Module not found가 계속되는 주요 원인 8가지

1. ./와 ../ 상대 경로를 잘못 작성한 경우
2. 파일 또는 폴더 이름에 오타가 있는 경우
3. 실제 파일과 import문의 대소문자가 다른 경우
4. 필요한 npm 패키지가 설치되지 않은 경우
5. 다른 프로젝트 폴더에 패키지를 설치한 경우
6. alias 경로 설정이 실제 빌드 설정과 맞지 않는 경우
7. 파일 이동·이름 변경 후 기존 import가 남아 있는 경우
8. ESM이나 빌드 도구의 모듈 해석 방식과 코드가 맞지 않는 경우
 
여러 해결법을 무작정 적용하기보다 에러 메시지에 표시된 경로 하나를 기준으로 실제 파일까지 추적하는 것이 훨씬 빠릅니다. 경로가 맞다면 그다음 패키지 설치와 프로젝트 설정으로 범위를 넓히면 됩니다.
 
 

Module not found 가장 쉬운 해결 순서

처음부터 node_modules를 삭제하거나 프로젝트를 새로 만들 필요는 없습니다. 아래 순서대로 간단한 원인부터 확인해 보세요.
 

1단계	에러에서 찾지 못한 모듈 이름 확인
2단계	내 파일인지 외부 패키지인지 구분
3단계	./, ../와 실제 폴더 위치 확인
4단계	파일명·대소문자·확장자 확인
5단계	외부 패키지라면 설치 상태 확인
6단계	package.json과 현재 작업 폴더 확인
7단계	alias와 모듈 관련 설정 확인
8단계	개발 서버를 재시작하고 다시 빌드

 
 

캐시 때문에 계속 보이는 오류일까?

경로와 패키지를 제대로 수정했는데 개발 서버에 이전 오류가 남아 있는 것처럼 보인다면 먼저 개발 서버를 종료한 뒤 다시 실행해 보세요. 설정 파일이나 환경을 변경한 경우 재시작해야 변경 사항이 제대로 반영되는 도구도 있습니다.
 
캐시 삭제나 node_modules 재설치는 그다음 단계로 생각하는 편이 좋습니다. 실제 원인이 파일 경로 오타라면 캐시를 아무리 삭제해도 문제가 해결되지 않기 때문입니다.
 
 

Cannot find module과 Module not found 차이는?

두 메시지는 모두 필요한 모듈을 찾지 못했다는 점에서 매우 비슷합니다. 다만 Cannot find module은 Node.js 실행 과정에서 자주 접할 수 있고, Module not found는 Webpack이나 프레임워크의 빌드 과정 등에서도 흔히 볼 수 있습니다.
 
실제 해결 과정에서는 메시지 이름만으로 판단하기보다 어떤 도구가 오류를 출력했는지와 어떤 경로를 찾지 못했는지 확인하는 것이 더 중요합니다. 두 오류 모두 경로와 패키지 설치 상태가 가장 먼저 확인할 항목입니다.
 
 

Module not found 오류를 예방하는 방법

파일을 이동하거나 이름을 변경할 때는 관련 import문도 함께 수정하고, 가능하면 에디터의 자동 import와 리팩터링 기능을 활용하세요. 패키지를 추가했다면 올바른 프로젝트에서 설치했는지와 package.json 반영 여부도 확인하는 습관이 좋습니다.
 
 
Module not found가 계속 발생한다면 가장 먼저 npm을 다시 설치하기보다 에러 메시지에 나온 경로를 직접 확인해 보세요. 로컬 파일이라면 경로·대소문자·확장자를, 외부 패키지라면 설치 위치와 package.json을 확인하면 됩니다.
 
그래도 해결되지 않는다면 alias와 ESM 설정, 빌드 도구 설정으로 범위를 넓혀보세요. 경로 → 파일명 → 설치 → 설정 → 재시작 순서만 기억해도 Module not found 오류를 훨씬 빠르게 해결할 수 있습니다.