프로젝트를 잃지 않고 Mac에서 node_modules 삭제하기
AskClean 팀 · 업데이트 2026-08-05
package.json과 올바른 lockfile이 온전하고 필요한 의존성을 다시 구할 수 있다면 프로젝트의 node_modules를 삭제해도 됩니다. 먼저 프로젝트별 용량과 재설치 조건을 확인하고 사용 중인 프로세스를 종료한 다음, 해당 폴더만 휴지통으로 옮기세요. 저장소가 지정한 패키지 관리자와 버전으로 다시 설치한 뒤 빌드와 테스트가 통과할 때까지 휴지통을 비우지 마세요.
node_modules와 프로젝트 원본 구분하기
node_modules는 설치된 의존성 트리이므로 조건이 맞으면 다시 만들 수 있습니다. 하지만 <project>/node_modules를 삭제하면 재설치가 끝날 때까지 그 프로젝트를 실행하거나 빌드할 수 없습니다. package.json, lockfile, 소스, 설정, 패치, 워크스페이스 정의와 Git 기록은 재설치에 필요한 입력이므로 삭제하면 안 됩니다. npm의 공유 다운로드 캐시는 보통 ~/.npm에 있으며 node_modules와 위치, 목적, 복구 범위가 모두 다릅니다.
실제로 재구성할 수 있는지 확인하기
lockfile은 필요하지만 완전한 백업은 아닙니다. package.json의 packageManager 필드와 저장소 문서에서 패키지 관리자 및 버전을 확인하세요. 사설 레지스트리 인증, VPN, Git 의존성, file: 의존성, 로컬 워크스페이스, Xcode Command Line Tools 같은 네이티브 빌드 환경, 설치 스크립트의 외부 다운로드에도 접근할 수 있어야 합니다. npm v12는 npm-shrinkwrap.json을 읽지 않으므로, 이 파일을 커밋한 기존 프로젝트는 같은 형식의 파일 이름을 package-lock.json으로 바꿔야 합니다. node_modules 안에만 적용한 수동 수정도 삭제하면 사라집니다.
- 프로젝트 루트에서 pwd와 du -sh ./node_modules를 실행하고 macOS 여유 공간을 기록합니다.
- package.json, packageManager 필드, 올바른 lockfile, 워크스페이스 설정, 커밋하지 않은 소스와 설정을 확인합니다. npm-shrinkwrap.json만 있는 기존 프로젝트는 npm v12를 쓰기 전에 같은 형식의 파일 이름을 package-lock.json으로 바꿉니다.
- 사설 레지스트리, Git·file: 의존성, 로컬 워크스페이스, 외부 다운로드와 필요한 빌드 도구에 접근할 수 있는지 확인하고 node_modules를 쓰는 프로세스를 종료합니다.
- 해당 프로젝트의 node_modules만 휴지통으로 옮긴 뒤, 저장소 루트에서 npm ci 또는 프로젝트가 지정한 pnpm install --frozen-lockfile, yarn install --immutable (Yarn Classic은 yarn install --frozen-lockfile), bun install --frozen-lockfile 절차로 재설치합니다.
- 빌드, 테스트, lint, 앱 실행을 확인하고 여유 공간을 다시 측정한 다음에만 휴지통을 비웁니다.
node_modules를 의존 패키지나 수동 수정의 유일한 사본으로 사용하지 마세요. 정확한 의존성을 다시 가져올 수 없고 다른 곳에도 원본이 없다면 삭제 후 기존 프로젝트를 재구성하지 못할 수 있습니다.
확인한 의존성 폴더 하나만 휴지통으로 옮기기
대상을 확인한 프로젝트에서 node_modules만 Finder의 휴지통으로 옮기고 상위 저장소는 선택하지 마세요. rm -rf ./node_modules는 휴지통을 거치지 않아 되돌릴 수 없으므로, 꼭 사용해야 한다면 프로젝트 루트에서 pwd와 대상을 다시 확인해야 합니다. 검증하지 않은 find 출력, 와일드카드 또는 빈 변수를 삭제 명령에 넘기지 마세요. npm 프로젝트는 package-lock.json이 기준일 때 저장소 루트에서 npm ci를 사용하고, pnpm·Yarn·Bun 프로젝트는 저장소가 지정한 lockfile 변경 방지 절차로 재설치하세요. monorepo에서는 루트 lockfile과 모든 워크스페이스를 하나의 의존성 시스템으로 다룹니다.
빌드·테스트·실행까지 검증하기
설치 성공만으로 복구가 끝난 것은 아닙니다. 프로젝트가 정한 빌드, 테스트, lint, 실행 절차를 수행해 네이티브 애드온과 라이프사이클 스크립트까지 동작하는지 확인하세요. 실패하면 휴지통에서 복원할 수 있을 때 되돌리고 인증, 네트워크, Node.js와 패키지 관리자 버전, 도구 체인, lockfile 불일치를 진단합니다. 원인을 분리할 수 있도록 같은 작업에서 npm 캐시, 패키지 관리자 저장소 또는 lockfile까지 함께 지우지 마세요. AskClean은 node_modules를 프로젝트 빌드 산출물로 표시하고 소스와 Git 기록은 삭제 후보에서 분리합니다.
삭제 판단과 복구 비용
Mac에서 용량이 큰 node_modules 폴더를 프로젝트별로 찾아 소스와 lockfile을 보호하고, 저장소가 지정한 패키지 관리자와 버전으로 안전하게 다시 설치하는 방법입니다.
| 항목·작업 | 확인 위치 | 삭제 또는 작업의 결과 |
|---|---|---|
| node_modules와 프로젝트 원본 구분하기 | <project>/node_modules | node_modules는 설치된 의존성 트리이므로 조건이 맞으면 다시 만들 수 있습니다. 하지만 <project>/node_modules를 삭제하면 재설치가 끝날 때까지 그 프로젝트를 실행하거나 빌드할 수 없습니다. package.json, lockfile, 소스, 설정, 패치, 워크스페이스 정의와 Git 기록은 재설치에 필요한 입력이므로 삭제하면 안 됩니다. npm의 공유 다운로드 캐시는 보통 ~/.npm에 있으며 node_modules와 위치, 목적, 복구 범위가 모두 다릅니다. |
| 실제로 재구성할 수 있는지 확인하기 | package.json + lockfile + 워크스페이스 설정 | lockfile은 필요하지만 완전한 백업은 아닙니다. package.json의 packageManager 필드와 저장소 문서에서 패키지 관리자 및 버전을 확인하세요. 사설 레지스트리 인증, VPN, Git 의존성, file: 의존성, 로컬 워크스페이스, Xcode Command Line Tools 같은 네이티브 빌드 환경, 설치 스크립트의 외부 다운로드에도 접근할 수 있어야 합니다. npm v12는 npm-shrinkwrap.json을 읽지 않으므로, 이 파일을 커밋한 기존 프로젝트는 같은 형식의 파일 이름을 package-lock.json으로 바꿔야 합니다. node_modules 안에만 적용한 수동 수정도 삭제하면 사라집니다. |
| 확인한 의존성 폴더 하나만 휴지통으로 옮기기 | 휴지통 / 패키지 관리자로 재설치 | 대상을 확인한 프로젝트에서 node_modules만 Finder의 휴지통으로 옮기고 상위 저장소는 선택하지 마세요. rm -rf ./node_modules는 휴지통을 거치지 않아 되돌릴 수 없으므로, 꼭 사용해야 한다면 프로젝트 루트에서 pwd와 대상을 다시 확인해야 합니다. 검증하지 않은 find 출력, 와일드카드 또는 빈 변수를 삭제 명령에 넘기지 마세요. npm 프로젝트는 package-lock.json이 기준일 때 저장소 루트에서 npm ci를 사용하고, pnpm·Yarn·Bun 프로젝트는 저장소가 지정한 lockfile 변경 방지 절차로 재설치하세요. monorepo에서는 루트 lockfile과 모든 워크스페이스를 하나의 의존성 시스템으로 다룹니다. |
| 빌드·테스트·실행까지 검증하기 | 빌드 + 테스트 + 앱 실행 | 설치 성공만으로 복구가 끝난 것은 아닙니다. 프로젝트가 정한 빌드, 테스트, lint, 실행 절차를 수행해 네이티브 애드온과 라이프사이클 스크립트까지 동작하는지 확인하세요. 실패하면 휴지통에서 복원할 수 있을 때 되돌리고 인증, 네트워크, Node.js와 패키지 관리자 버전, 도구 체인, lockfile 불일치를 진단합니다. 원인을 분리할 수 있도록 같은 작업에서 npm 캐시, 패키지 관리자 저장소 또는 lockfile까지 함께 지우지 마세요. AskClean은 node_modules를 프로젝트 빌드 산출물로 표시하고 소스와 Git 기록은 삭제 후보에서 분리합니다. |
자주 묻는 질문
Mac에서 node_modules를 삭제해도 안전한가요?
package.json, 올바른 lockfile, 워크스페이스 설정, 소스와 필요한 의존성에 대한 접근이 남아 있다면 보통 다시 만들 수 있습니다. 다만 재설치가 끝날 때까지 프로젝트를 실행하거나 빌드할 수 없습니다.
package-lock.json도 함께 삭제해야 하나요?
아닙니다. package-lock.json은 npm ci로 같은 의존성 해석 결과를 재현하는 입력입니다. npm v12는 npm-shrinkwrap.json을 읽지 않으므로, 기존 프로젝트에서는 같은 형식의 해당 파일 이름을 package-lock.json으로 바꾼 뒤 사용해야 합니다.
node_modules와 npm 캐시는 같은 것인가요?
아닙니다. node_modules는 프로젝트 하나에 설치된 의존성 트리이고, npm의 공유 캐시는 보통 ~/.npm에 있습니다. 하나를 삭제해도 다른 하나는 삭제되지 않습니다.
참고 자료