Claude Code v2.1.12 업데이트 시 ENOTEMPTY: directory not empty 에러가 발생하는 경우 기존 설치 폴더와 임시 폴더를 삭제한 후 재설치하면 해결됩니다. npm이 업데이트 과정에서 디렉토리 이름 변경(rename)을 시도할 때 이전 실패로 남은 임시 폴더나 비어있지 않은 디렉토리가 충돌을 일으켜 발생하는 문제입니다.
아침에 Claude Code 켰는데 이게 뭐야
진짜 짜증나지 않아요?
어제까지만 해도 잘 되던 Claude Code인데요.
오늘 켰더니 터미널 밑에 빨간 글씨로 이렇게 떠있더라고요.
✗ Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code
에이 설마 했죠.
그냥 업데이트 한번 하면 되겠지 싶었는데.
npm i -g @anthropic-ai/claude-code
이거 쳤더니 이번엔 또 다른 에러가.
npm ERR! code ENOTEMPTY npm ERR! ENOTEMPTY: directory not empty, rename '/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code' -> '/opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V'
진짜 뭐가 문제인지도 모르겠고.
claude doctor 쳐봐도 해결 안 되고.
구글링해도 영어로 된 GitHub 이슈들만 잔뜩.
이거 어떻게 해야 하나 막막하더라고요.
근데 알고 보니 해결법은 진짜 간단했어요.
왜 이런 에러가 생기는 건데
먼저 이해하고 가야 해요.
npm이 글로벌 패키지를 업데이트할 때는 이런 과정을 거쳐요.
1단계: 기존 폴더를 임시 이름으로 rename 2단계: 새 버전을 원래 이름으로 설치 3단계: 임시 폴더 삭제
그런데 이 과정에서 뭔가 잘못되면?
이전 업데이트가 실패했는데 임시 폴더가 안 지워졌다거나.
다른 프로세스가 동시에 같은 폴더를 건드린다거나.
그러면 npm이 rename 시도할 때 “어? 이미 폴더 있네?” 하면서 멈춰버려요.
그게 바로 ENOTEMPTY 에러.
“Error, Not Empty”의 줄임말이에요.
실제로 확인해보니
제 맥에서 /opt/homebrew/lib/node_modules/@anthropic-ai/ 폴더를 보니까요.
진짜로 .claude-code-2DTsDk1V 같은 임시 폴더가 남아있더라고요.
이전 업데이트 실패할 때 생긴 거죠.
npm은 이걸 보고 “아 rename할 수 없네” 하면서 에러 뱉은 거고.
해결법은 진짜 간단해요
복잡하게 생각할 필요 없어요.
그냥 기존 폴더 싹 다 지우고 새로 깔면 돼요.
macOS / Linux 사용자
터미널 열고 이거 복붙하세요.
rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-*
이게 뭐냐면요.
claude-code 폴더랑 .claude-code-로 시작하는 모든 임시 폴더를 삭제하는 명령어예요.
혹시 Homebrew 안 쓰고 직접 Node.js 설치했으면?
경로가 다를 수 있어요.
rm -rf /usr/local/lib/node_modules/@anthropic-ai/claude-code /usr/local/lib/node_modules/@anthropic-ai/.claude-code-*
이렇게 바꿔서 쳐보세요.
Windows 사용자
PowerShell 관리자 권한으로 여세요.
Remove-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code" Remove-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@anthropic-ai\.claude-code-*"
이렇게 치면 돼요.
그 다음
이제 새로 설치하면 끝이에요.
npm i -g @anthropic-ai/claude-code
5~10초 정도 기다리면요.
changed 1 package in 7s
이런 메시지 뜨면서 설치 완료될 거예요.
버전 확인
진짜 됐는지 확인해볼까요?
claude --version
쳐보세요.
@anthropic-ai/claude-code/2.1.12 darwin-arm64 node-v22.12.0
이렇게 최신 버전으로 뜨면 성공이에요.
왜 폴더 삭제가 답일까
“어 근데 왜 삭제하면 되는 건데?”
궁금하지 않으세요?
npm은 상태를 폴더 이름으로 관리해요.
정상 폴더: claude-code 임시 폴더: .claude-code-xxxxx
업데이트 실패하면 이 임시 폴더가 남아요.
그러면 다음 업데이트 때 또 실패해요.
왜냐면 npm이 rename하려는 이름이 이미 존재하니까.
그래서 아예 깨끗이 지우고 새로 설치하는 게 답이에요.
설정이나 API 키는요?
걱정 마세요.
Claude Code 설정은 ~/.claude/ 폴더에 따로 저장돼요.
node_modules 지워도 설정은 안 날아가요.
다른 방법들도 시도해봤어요
물론 폴더 삭제가 제일 확실하긴 한데요.
혹시나 싶어서 다른 방법들도 해봤어요.
claude doctor 명령어
claude doctor
이거 쳐보면요.
시스템 체크는 해주는데.
이미 발생한 ENOTEMPTY 에러는 못 고쳐요.
진단만 해주지 치료는 안 해줘요.
npm 캐시 클리어
npm cache clean --force npm i -g @anthropic-ai/claude-code
이것도 해봤는데요.
임시 폴더가 남아있으면 똑같이 실패해요.
캐시 문제가 아니라 폴더 충돌 문제거든요.
npx로 임시 실행
npx @anthropic-ai/claude-code
이건 진짜 급할 때 쓸 수 있어요.
글로벌 설치 안 하고 임시로 실행하는 거예요.
근데 매번 이렇게 쓰긴 불편하죠.
그냥 글로벌 설치 제대로 해결하는 게 나아요.
같은 문제 겪은 사람들 진짜 많아요
GitHub 이슈 보니까요.
2026년 1월에만 해도 비슷한 문제 보고가 수십 개예요.
Issue #5226: Auto-update failed 계속 뜸
어떤 분은 수동으로 업데이트했는데도요.
터미널 밑에 “Auto-update failed” 메시지가 계속 떠있대요.
실제로는 최신 버전인데도.
이것도 임시 폴더 문제였어요.
Issue #18114: Auto-Update 아예 안 됨
자동 업데이트가 트리거조차 안 되는 경우도 있었어요.
config.json에는 최신 업데이트 받기로 설정돼있는데.
실행하면 계속 구버전이래요.
claude update 쳐도 “이미 최신 버전이에요” 하면서 거짓말하고.
Issue #16673: Invalid Version 2.1.0
2.1.0으로 업데이트한 후에.
실행하면 버전 에러가 뜨는 경우도 있었어요.
다 비슷한 원인이에요.
npm 글로벌 패키지 관리 과정에서 생긴 꼬임.
실전 팁: 이렇게 하면 문제 예방돼요
한번 고쳤으면 다시는 안 겪고 싶잖아요.
1. 동시에 여러 터미널에서 업데이트 금지
터미널 2개 켜놓고요.
둘 다에서 npm i -g 하면 충돌 날 수 있어요.
업데이트는 한 곳에서만 하세요.
2. 업데이트 중에 Ctrl+C 누르지 마세요
진짜 급해도 기다리세요.
중간에 취소하면 임시 폴더가 남아요.
그게 다음 업데이트 때 문제 일으켜요.
3. 정기적으로 임시 폴더 확인
한 달에 한 번씩요.
ls -la /opt/homebrew/lib/node_modules/@anthropic-ai/
이렇게 쳐서 .claude-code-xxxxx 같은 폴더 있으면 지우세요.
4. 자동 업데이트보다 수동 업데이트 추천
개인적으로는요.
Claude Code 자동 업데이트 기능보다.
그냥 가끔 npm i -g @anthropic-ai/claude-code 수동으로 치는 게 나은 것 같아요.
더 안정적이거든요.
이 방법으로 해결 안 되면?
진짜 드문 경우인데요.
위 방법대로 해도 안 되면 이것들 체크해보세요.
Node.js 버전 확인
node --version
Node.js 18 이상이어야 해요.
16 이하면 업그레이드 필요해요.
# macOS (Homebrew) brew upgrade node # Linux (nvm) nvm install --lts nvm use --lts
npm 권한 문제
macOS/Linux에서요.
/usr/local/lib/node_modules/ 같은 시스템 폴더에 접근 못 할 수도 있어요.
sudo npm i -g @anthropic-ai/claude-code
sudo 붙여서 시도해보세요.
근데 이건 임시방편이에요.
장기적으로는 nvm 쓰는 게 나아요.
완전히 새로 시작
정 안 되면요.
Node.js부터 다시 깔아요.
# macOS brew uninstall node brew install node # 그 다음 npm i -g @anthropic-ai/claude-code
이렇게 하면 100% 해결돼요.
Windows에서는 좀 달라요
Windows 사용자면요.
경로가 좀 다를 수 있어요.
npm 글로벌 경로 확인
npm config get prefix
이거 쳐보세요.
나오는 경로를 메모하고요.
거기 가서 node_modules\@anthropic-ai\ 폴더 찾으세요.
WSL 사용하면
WSL에서 Claude Code 쓰는 분들 있잖아요.
그럼 Linux 방법이랑 똑같아요.
rm -rf /usr/local/lib/node_modules/@anthropic-ai/claude-code npm i -g @anthropic-ai/claude-code
이렇게 하면 돼요.
PowerShell 권한
Windows는 관리자 권한 꼭 필요해요.
PowerShell 우클릭 → “관리자 권한으로 실행” 하세요.
안 그러면 폴더 삭제할 때 권한 에러 나요.
저는 이렇게 해결했어요 (실제 경험)
제 경우를 정리하면요.
1단계: 에러 발견
아침에 Claude Code 켜니까 Auto-update failed 메시지.
npm i -g 쳐봤더니 ENOTEMPTY 에러.
2단계: 폴더 확인
ls -la /opt/homebrew/lib/node_modules/@anthropic-ai/
쳐봤더니 .claude-code-2DTsDk1V 임시 폴더 발견.
3단계: 싹 삭제
rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-*
4단계: 재설치
npm i -g @anthropic-ai/claude-code
7초 만에 설치 완료.
5단계: 확인
claude --version
2.1.12 나오면서 해결.
처음부터 끝까지 5분도 안 걸렸어요.
비슷한 에러들도 같은 방법으로 해결
사실 이 ENOTEMPTY 에러는요.
Claude Code만의 문제가 아니에요.
npm 글로벌 패키지 업데이트 과정에서 흔히 생겨요.
firebase-tools 업데이트 에러
npm ERR! ENOTEMPTY: directory not empty, rename '/usr/local/lib/node_modules/firebase-tools'
이것도 똑같이 해결해요.
rm -rf /usr/local/lib/node_modules/firebase-tools npm i -g firebase-tools
n8n 업데이트 에러
npm ERR! ENOTEMPTY: directory not empty, rename '/usr/local/lib/node_modules/n8n'
이것도요.
rm -rf /usr/local/lib/node_modules/n8n npm i -g n8n
왜 npm은 이렇게 만들었을까
npm이 업데이트할 때 rename 전략 쓰는 이유는요.
원자적(atomic) 연산이 가능해서예요.
rename은 성공하거나 실패하거나 둘 중 하나거든요.
중간 상태가 없어요.
그래서 안전하게 rollback할 수 있어요.
근데 실제로는 이렇게 임시 폴더 남는 문제가 생기네요.
자주 묻는 질문
Q1: 폴더 지우면 설정 날아가나요?
아니요.
Claude Code 설정은 ~/.claude/ 폴더에 있어요.
API 키, 프로젝트 설정, 대화 히스토리 다 그대로 남아요.
node_modules는 그냥 실행 파일만 있는 거예요.
Q2: sudo 써야 하나요?
macOS에서 Homebrew로 Node.js 설치했으면요.
sudo 필요 없어요.
근데 /usr/local/에 직접 설치했으면 sudo 필요할 수 있어요.
권한 에러 나면 그때 sudo 붙이세요.
Q3: 다른 npm 패키지도 지워지나요?
아니요.
위 명령어는 @anthropic-ai/claude-code만 지워요.
다른 글로벌 패키지는 안전해요.
확인하고 싶으면요.
npm list -g --depth=0
이거 쳐서 설치된 패키지 목록 보세요.
Q4: 자동 업데이트 끄는 방법은?
~/.claude/config.json 파일에서요.
{
"autoUpdate": false
}
이렇게 바꾸면 자동 업데이트 안 돼요.
수동으로만 업데이트하고 싶을 때 유용해요.
Q5: WSL에서 경로가 달라요
WSL은 Linux 환경이라요.
보통 /usr/local/lib/node_modules/ 또는 /home/{username}/.nvm/versions/node/{version}/lib/node_modules/
여기에 있어요.
which claude
쳐보면 정확한 경로 나와요.
앞으로는 이렇게 하세요
한번 고쳤으니 다시는 안 겪으려면요.
업데이트 전 체크리스트
- 다른 터미널에서 npm 명령어 실행 중인지 확인
- Claude Code 완전히 종료
- 터미널 하나만 열어서 업데이트
- 완료될 때까지 Ctrl+C 누르지 말기
정기 점검
한 달에 한 번씩요.
ls -la /opt/homebrew/lib/node_modules/@anthropic-ai/
이거 쳐서 임시 폴더 있는지 확인하세요.
.claude-code-로 시작하는 폴더 보이면 지우세요.
nvm 사용 고려
Node.js 버전 관리가 필요하면요.
nvm 쓰는 게 나아요.
# macOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 그 다음 nvm install --lts nvm use --lts npm i -g @anthropic-ai/claude-code
이렇게 하면 권한 문제도 없고 관리도 편해요.
정리하면
Claude Code Auto-update failed 에러.
그리고 npm ENOTEMPTY 에러.
이거 해결법 진짜 간단해요.
핵심 3줄 요약:
- 기존 폴더 + 임시 폴더 싹 삭제
npm i -g @anthropic-ai/claude-code재설치claude --version으로 확인
# macOS (Homebrew) rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-* npm i -g @anthropic-ai/claude-code # macOS/Linux (직접 설치) rm -rf /usr/local/lib/node_modules/@anthropic-ai/claude-code /usr/local/lib/node_modules/@anthropic-ai/.claude-code-* npm i -g @anthropic-ai/claude-code # Windows Remove-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code" npm i -g @anthropic-ai/claude-code
이거 복붙해서 쳐보세요.
5분 안에 해결될 거예요.
설정이나 API 키는 안 날아가니까 걱정 마시고요.
혹시 안 되면요.
Node.js 버전 확인하고.
권한 문제면 sudo 붙여보고.
그래도 안 되면 Node.js 재설치.
이 순서로 하면 100% 해결돼요.
저도 이렇게 해서 해결했거든요.
Sources: