npx/uvx 사용 시 캐시 누적 문제와 해결 방법

Node.js 나 Python 을 다뤄봤다면 `npx`나 `uvx` 같은 도구를 한번쯤 들어봤을거다. 프로젝트를 뚝딱 시작하거나 특정 명령줄 도구를 툭 던져 실행할 때 이들만큼 유용한 게 또 있을까? 하지만 이런 도구들을 꾸준히 쓰다 보면 눈치채지 못하는 문제가 하나 숨어 있다. 바로 지속적으로 쌓이는 캐시 파일들이다. 실제로 캐시 폴더를 확인해본 결과 거의 1GB 에 육박하는 캐시파일들이 공간을 차지하고 있었다. 이번 글에서는 npx와 uvx가 캐시를 다루는 방식과, 이 때문에 불거질 수 있는 문제들, 그리고 내 개발 환경을 언제나 산뜻하게 유지하기 위한 캐시 정리 꿀팁을 전해준다.

(출처 - https://tebilisim.com/en/what-is-cache-and-what-is-its-purpose-why-is-cache-used/)

 

---

 

npx와 uvx, 그 편리함 뒤에 숨은 캐시의 그림자

`npx` (Node.js, npm)와 `uvx` (Python, uv의 일부)는 놀랍도록 닮은 철학을 공유한다.

• 설치 부담 제로: 번거롭게 전역(global) 환경에 패키지를 깔아둘 필요가 없다.
• 즉석 다운로드: 명령을 내릴 때만 필요한 패키지를 임시 공간에 불러와 사용한다.
• 독립적인 공간: 실행되는 도구들이 내 시스템의 다른 패키지나 프로젝트와 섞이지 않도록 깔끔하게 격리한다.

이 덕분에 `create-react-app`으로 React 프로젝트를 후루룩 만들거나, `uvx black`으로 Python 코드를 쓱싹 포매팅할 때 따로 설치 과정을 거칠 필요가 없는 거다. 참 편리하다.

그런데 여기에 한 가지 오해가 싹틀 수 있다. "임시 다운로드", "실행 후 정리"라는 말 때문에 많은 개발자들이 명령이 끝나면 모든 캐시 파일이 순식간에 사라지는 줄로 착각하기 쉽다는 점이다. 하지만 실제는 좀 다르다. npx와 uvx는 다음 실행 때 시간을 아끼기 위해, 그리고 특정 도구를 실행하는 데 쓰였던 파일들을 캐시에 고이 모셔두는 경향이 있다. 특히 `create-react-react`처럼 복잡한 작업을 하거나 자주 쓰일 법한 도구들은 캐시에 더 오래 머물러 있다. 이렇게 되면 처음엔 미미하던 캐시가 시간이 흐를수록 쌓이고 쌓여, 어느새 수백 MB를 넘어 기가바이트 단위의 디스크 공간을 야금야금 차지하게 된다. 심지어 패키지 버전이 변경됨에 따라 버전별로 다른 캐시가 쌓여간다.

 

---

 

캐시가 쌓이면 왜 문제인가?

캐시가 끊임없이 불어나는 현상은 생각보다 성가신 문제를 일으킬 수 있다.

• 디스크 공간 낭비: 쓰지도 않는 파일들이 귀한 저장 공간을 갉아먹는다. 특히 빠른 SSD를 쓴다면 더더욱 아까운 일이다.
• 혹시 모를 오류: 아주 드물게는 오래되거나 손상된 캐시 파일 때문에 예상치 못한 오류가 고개를 들 수도 있다.
• 개발 환경 오염: 개발 환경은 간결하고 예측 가능할수록 좋다. 쓸모없는 캐시는 이런 바람직한 원칙을 거스르는 주범이다.

 

---

 

npx 및 uvx 캐시 청소 가이드

맥 환경과 윈도우 환경에서의 캐시 경로가 서로 상이하다. 아래 설치된 경로를 바탕으로 실제 설치되어있는 캐시 폴더를 직접 확인하고 캐시 정리 전후의 용량 변화를 확인해보자. 

`~` 또는 `$HOME`은 사용자 홈 디렉토리를 나타낸다.
`%LOCALAPPDATA%`는 Windows의 환경 변수로, 현재 사용자의 로컬 애플리케이션 데이터 폴더를 가리킨다.

1. npx (npm) 캐시 청소하기

`npx` 캐시는 보통 npm 캐시 폴더 안의 `_npx`라는 곳에 자리 잡고 있다. 정확한 npm 캐시 경로는 `npm config get cache` 명령어로 확인 가능하다.

• macOS / Linux:(예시: `/Users/yourusername/.npm/_npx`)

~/.npm/_npx

• Windows:(예시: `C:\Users\yourusername\AppData\Local\npm-cache\_npx`)

%LOCALAPPDATA%\npm-cache\_npx

 

가장 손쉬운 방법: clear-npx-cache 패키지 활용

clear-npx-cache

 

`npx`는 특별히 캐시 관리를 위한 전용 명령어를 제공하지 않는다. 따라서 이 방법이 가장 간편하고 안전한 npx 캐시 청소 방법이다. 이 명령어는 `clear-npx-cache`라는 npm 패키지를 npx로 잠깐 실행시켜 _npx 캐시 디렉토리를 찾아 깔끔하게 지운다. 따로 뭘 설치할 필요도 없어 무척 편리하다.

npx clear-npx-cache

 

직접 _npx 폴더 삭제하기

캐시 폴더의 위치를 알고 있다면 직접 찾아가 지울 수도 있다. 아래와 같은 특별한 명령어 없이 그냥 해당 폴더를 그냥 삭제해도 무방하다.

• macOS / Linux: `rm -rf ~/.npm/_npx`
• Windows (명령 프롬프트): `rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx`
• 경고: 이 명령어들은 되돌릴 수 없으니, 경로를 다시 한번 확인하고 신중하게 사용해야 한다. 엉뚱한 파일을 날려버릴 수도 있다.

 

---

 

2. uvx (uv) 캐시 청소하기

`uvx`는 `uv`의 한 부분이며, `uv`는 캐시 관리를 위한 전용 명령어를 제공한다. `uv cache dir` 명령어를 통해 정확한 캐시 경로를 출력해보자.

• macOS:(예시: /`Users/yourusername/.cache/uv`)

$HOME/.cache/uv

• Windows:(예시: `C:\Users\yourusername\AppData\Local\uv\cache`)

%LOCALAPPDATA%\uv\cache

 

모든 캐시 항목 삭제 (강력 추천)

`uv`가 쓰는 모든 캐시(다운로드된 패키지, 빌드 결과물, 메타데이터 등)를 지워 디스크 공간을 확보할 때 유용하다.

uv cache clean

사용되지 않는 캐시 항목 정리 (정기 관리용)

더 이상 필요 없거나 오래된 캐시 항목들을 청소한다. `uv cache clean`보다 부담이 덜하니, 주기적으로 돌려주면 캐시 크기를 관리하는 데 좋다.

uv cache prune

 

---

 

깔끔한 개발 환경을 위한 소소한 습관

`npx`와 `uvx`는 개발자의 생산성을 한껏 끌어올려 주는 고마운 도구들이다. 하지만 그 편리함에만 취해 캐시 관리를 등한시한다면, 어느새 내 컴퓨터가 쓸모없는 파일들로 가득 차 버릴 수 있다. 이제부터라도 `npx clear-npx-cache`나 `uv cache prune` 같은 명령어를 주기적으로 실행하여 개발 환경을 언제나 깨끗하게 유지하는 습관을 들이는 것을 추천한다. 이렇게 하면 디스크 공간을 효율적으로 사용하고, 잠재적인 오류를 줄이며, 훨씬 더 쾌적한 개발 경험을 할 수 있을 것이다.