node_modules 삭제해도 되나요? 안전한 조건과 다시 설치하는 방법

프로젝트 용량이 너무 커졌거나 의존성 오류가 반복되면 node_modules 삭제해도 되나요라는 고민이 생겨요. 이 폴더는 설치된 패키지를 담는 곳이라 프로젝트 소스와 역할이 달라요.

하지만 다시 설치할 기준과 접근 권한이 남아 있는지 먼저 확인해야 해요. 특히 직접 수정한 패키지와 비공개 패키지는 삭제 뒤 복구가 어려울 수 있어요.

node_modules 삭제해도 되나요?

일반적인 로컬 Node.js 프로젝트라면 조건을 확인한 뒤 삭제해도 돼요. node_modules에는 npm, Yarn, pnpm이 설치한 라이브러리와 실행 파일이 들어 있어요.

삭제 직후에는 개발 서버, 테스트, 빌드가 실패할 수 있어요. 같은 패키지 관리자와 잠금 파일로 재설치를 마치면 node_modules가 다시 생성돼요.

다만 운영체제, CPU, Node.js 버전, 설치 옵션이 달라지면 네이티브 모듈과 설치 결과가 완전히 같지 않을 수 있어요.

node_modules를 삭제해도 되는 이유

직접 작성한 코드는 보통 src, app, pages 같은 프로젝트 폴더에 있어요. node_modules는 그 코드를 실행하거나 빌드할 때 필요한 외부 패키지를 설치한 폴더예요.

npm은 package.json의 의존성 목록을 읽고 로컬 node_modules에 패키지를 설치해요. package-lock.json이 package.json과 맞으면 잠금 파일에 기록된 버전을 사용해요.

삭제하기 전에 확인해야 할 파일

먼저 프로젝트 루트에 package.json이 있는지 확인하세요. npm은 package-lock.json, Yarn은 yarn.lock, pnpm은 pnpm-lock.yaml이 함께 있는지 살펴봐요.

package.json의 packageManager, engines, .nvmrc도 확인하면 사용하던 도구와 Node.js 버전을 찾는 데 도움이 돼요.

git status로 소스와 잠금 파일의 미저장 변경을 확인하세요. node_modules는 보통 Git에서 제외되므로 내부 수정 여부는 별도로 기억하거나 백업해야 해요.

node_modules를 지우면 안 되는 경우

node_modules 안의 패키지 파일을 직접 수정했다면 바로 삭제하지 마세요. 변경분을 원본 소스, 포크, patch-package 같은 재현 가능한 패치로 옮기지 않으면 복구하기 어려워요.

비공개 레지스트리가 닫혔거나 패키지가 삭제된 경우도 위험해요. 완전 오프라인 장비, 오래된 네이티브 모듈, 사내 패키지는 재설치 가능 여부를 먼저 시험해야 해요.

file:, link:, Git URL로 연결된 의존성이 있다면 해당 로컬 경로나 저장소도 남아 있어야 해요.

Yarn Modern은 nodeLinker 설정에 따라 node_modules 대신 Plug’n’Play를 사용할 수 있어요. node_modules가 없다면 .pnp.cjs나 .yarn 폴더를 같은 대상으로 보고 지우지 말고 .yarnrc.yml과 프로젝트 정책을 먼저 확인하세요.

Windows·macOS·Linux에서 안전하게 삭제하는 방법

개발 서버와 빌드 작업을 중지하고, 터미널에서 프로젝트 루트인지 확인하세요. 아래 명령은 휴지통을 거치지 않을 수 있으므로 경로를 한 번 더 확인해야 해요.

Windows PowerShell

Get-Location으로 현재 위치를 확인한 뒤 실행해요.

Remove-Item -LiteralPath .node_modules -Recurse -Force

Windows 명령 프롬프트

cd로 프로젝트 폴더에 들어간 뒤 실행해요.

rmdir /s /q node_modules

macOS·Linux 터미널

pwd로 현재 위치를 확인한 뒤 실행해요.

rm -rf node_modules

Windows에서 파일 사용 중 오류가 나면 실행 중인 Node.js 프로세스와 편집기 터미널을 먼저 닫아요. 관리자 권한보다 파일을 잡고 있는 프로세스를 종료하는 것이 우선이에요.

npm·Yarn·pnpm으로 다시 설치하는 방법

삭제 뒤에는 기존 프로젝트가 사용하던 패키지 관리자를 그대로 써야 해요. 잠금 파일이 여러 종류라면 임의로 섞지 말고 Git 기록과 package.json의 packageManager 항목을 확인하세요.

npm ci는 기존 package-lock.json이 필요하고 package.json과 맞지 않으면 오류로 중단해요. 실행 전 node_modules가 남아 있어도 npm ci가 자동으로 지운 뒤 전체 의존성을 다시 설치해요.

Yarn Modern의 --frozen-lockfile은 호환 별칭이고 앞으로 제거될 수 있어요. 최신 프로젝트는 --immutable을 사용하는 편이 좋아요.

pnpm은 프로젝트 node_modules에 링크 구조를 만들고 패키지 데이터를 공용 저장소에 보관해요. 프로젝트 폴더만 지워서는 공용 저장소 용량이 모두 줄지 않으며, 미사용 패키지 정리는 pnpm store prune으로 따로 진행해요.

삭제 후 오류가 발생했을 때 해결 순서

1. 현재 폴더와 잠금 파일을 확인해요

package.json이 보이는 프로젝트 루트에서 설치 명령을 실행했는지 확인하세요. 잠금 파일 종류와 실행한 패키지 관리자가 일치해야 해요.

2. Node.js와 패키지 관리자 버전을 확인해요

node -v, npm -v, yarn -v, pnpm -v로 버전을 확인하세요. 프로젝트의 engines, .nvmrc, packageManager와 맞추는 것이 우선이에요.

3. 잠금 파일 불일치를 해결해요

npm ci가 잠금 파일 불일치로 멈춰도 package-lock.json을 바로 삭제하지 마세요. Git에서 정상 파일을 복원하거나 의도한 변경인지 확인한 뒤 npm install로 갱신하고 차이를 검토해요.

4. 인증과 설치 스크립트를 확인해요

401·403 오류는 비공개 레지스트리 인증 문제일 수 있어요. .npmrc의 레지스트리 주소와 토큰 권한을 확인하고, 회사 정책상 설치 스크립트 승인이 필요한지도 살펴봐요.

5. 네이티브 모듈과 캐시를 점검해요

컴파일 오류는 Python, C/C++ 빌드 도구, 운영체제·CPU에 맞는 바이너리가 필요한 네이티브 모듈에서 생길 수 있어요.

npm 캐시는 먼저 npm cache verify로 검사하세요. 단순 설치 오류만으로 npm cache clean --force까지 실행할 필요는 없어요.

자주 묻는 질문