Mac에서 Hugging Face 캐시를 안전하게 삭제하는 방법
AskClean 팀 · 업데이트 2026-11-02
Mac에서 Hugging Face 캐시 공간을 확보하려면 먼저 앱이 실제로 쓰는 캐시를 찾고, hf cache ls로 내용을 확인한 다음, hf cache rm --dry-run으로 지울 저장소나 리비전을 미리 보세요. 오프라인에서 필요한 모델과 직접 만든 결과물은 보관하고, 공유 blob을 직접 지우거나 HF_HOME 폴더 전체를 무작정 삭제하지 마세요.

실제 경로와 보관할 데이터 확인하기
일반적인 Hub 캐시 위치는 ~/.cache/huggingface/hub입니다. HF_HUB_CACHE는 Hub 저장소 캐시 위치를 직접 지정하고, HF_HOME은 더 넓은 Hugging Face 홈 디렉터리를 바꿉니다. HF_HOME이 설정되지 않았다면 XDG_CACHE_HOME이 기본 위치에 영향을 줄 수 있고, 앱이 cache_dir 인수로 다른 위치를 쓸 수도 있습니다. GUI 앱, 노트북 커널, 명령줄 프로젝트는 환경 설정이 다를 수 있으므로 따로 확인하세요. HF_HOME에는 인증 정보도 있을 수 있으니 전체를 삭제하지 말고, 도움을 요청할 때도 민감한 값을 지운 관련 설정만 공유하세요.
미세 조정한 체크포인트, 어댑터, 토크나이저 변경, 변환 결과, 비공개 데이터셋, 노트북, 프롬프트, 프로젝트 설정은 다시 받을 수 없을 수 있습니다. 내려받은 기본 모델은 다시 받을 수 있어도 로컬 어댑터나 변환 방법은 이 Mac에만 있을 수 있으니, 모델 관련 공간을 정리하기 전에 백업하고 확인하세요. 일부 백업 도구는 CACHEDIR.TAG가 있는 캐시를 건너뛰므로 실제로 필요한 파일이 백업에 들어 있는지 검증해야 합니다. 복원하고 앱을 다시 작동시킬 방법을 모르는 항목은 일단 남겨 두고, 접근 시각만 보고 필요 없다고 판단하지 마세요.
저장소와 리비전을 먼저 살펴보기
캐시를 쓰는 앱, 다운로드, 작업을 먼저 중지하세요. hf cache ls --no-truncate로 전체 저장소 ID를 확인한 다음, hf cache ls --revisions --no-truncate --show-warnings로 전체 리비전 해시와 캐시 문제를 확인합니다. 저희가 검증한 버전에서는 자세한 경고가 기본적으로 숨겨져 있습니다. 사용자 지정 Hub 캐시라면 모든 명령에 같은 --cache-dir 값을 넘기세요. 읽을 수 없거나 일관되지 않은 항목에 대한 경고는 삭제 전에 확인하고, 현재 사용량과 여유 공간을 기록하세요. 출력에 기밀 프로젝트가 드러난다면 외부에 공유하지 마세요.
미리보기로 삭제 범위 확정하기
hf cache rm에는 목록에서 확인한 전체 저장소 ID나 리비전 해시를 사용하고, 먼저 --dry-run을 붙이세요. 모델 저장소는 CLI가 보여 주는 model/ 접두사를 그대로 유지해야 하며, 디스크에 있는 models-- 폴더 이름과는 다른 식별자입니다. 리비전 하나만 지우려면 전체 해시를 쓰고 어느 저장소에 속하는지 확인하세요. 미리보기에는 대상 요약과 예상 확보 용량이 표시되지만 파일별 목록은 아닙니다. 저장소를 대상으로 지정하면 그 안의 모든 캐시 리비전이 포함됩니다.
범위를 확인했다면 같은 대상과 같은 캐시 경로로 --dry-run만 빼고 다시 실행하되, 마지막 확인 프롬프트는 켜 두세요. 목록이 예상과 달라지거나 미리보기가 실패하면 중단하고 원인을 확인합니다. 리비전끼리, 일부 구조에서는 저장소끼리도 blob을 공유하므로 Finder에서 개별 파일을 지우지 말고 Hugging Face 캐시 관리 도구에 맡기세요. 표시된 크기를 단순히 더하면 같은 파일을 여러 번 세게 됩니다.
캐시 삭제는 파일을 휴지통으로 옮기지 않고 바로 지웁니다. 지운 리비전을 복원하려면 백업이 있거나 다시 내려받을 수 있어야 합니다. 비공개 모델, 접근 승인이 필요한 모델, 더 이상 공개되지 않는 모델, 로컬에서 수정한 모델, 오프라인에서 필요한 모델은 확인이 끝날 때까지 백업을 남겨 두세요.
prune과 다른 캐시를 구분하기
저희가 검증한 2.0.0 CLI에서 hf cache prune --dry-run은 detached 리비전과 완료되지 않은 다운로드를 미리 보여 줍니다. detached 리비전은 캐시 안에 이름 붙은 참조가 없을 뿐, 프로젝트가 그 리비전을 정확히 지정해 쓰고 있을 수 있습니다. 후보를 하나씩 확인하고 진행 중인 다운로드를 멈춘 뒤 진행하세요. 개발용 Mac에서 처음 정리할 때는 한꺼번에 쓸어 담기보다 명확한 대상 하나를 지우는 편이 결과를 판단하기 쉽습니다.
HF_DATASETS_CACHE에 생성된 데이터셋 캐시는 Hub 다운로드와 별개라서, Hub 리비전을 지워도 Arrow 데이터나 변환 결과는 남을 수 있습니다. Xet 전송 캐시와 local_dir로 받은 파일도 따로 확인하고, 그 폴더에서 직접 수정한 파일은 보관하세요. 다시 내려받아도 로컬에서 수정한 내용은 돌아오지 않습니다. 분류별로 확인하지 않은 채 HF_HOME 전체를 삭제하지 마세요.
남겨 둔 모델이 작동하는지 검증하기
같은 방식으로 다시 측정한 뒤, 남기기로 한 모델과 리비전을 불러와 결과를 아는 작은 작업을 실행하세요. Python 라이브러리를 임포트하는 것만으로는 모델 파일이 정상인지 알 수 없습니다. 오프라인 사용이 필요하다면 실제로 네트워크를 끊고 시험하세요. 확인에 실패하면 정리를 멈추고, 앱이 점검한 환경을 쓰는지와 지운 파일이 필요한지 확인한 다음, 접근 권한과 여유 공간을 확인하고 백업이나 다시 내려받기로 복원하세요. 필요한 모델을 지웠다가 다시 받기를 반복하게 된다면 정리 대상이나 저장 공간 계획을 바꿔야 합니다.
외장 드라이브로 옮길 때는 여유 공간, 권한, 심볼릭 링크 지원을 확인하고, 스냅샷과 공유 blob을 잇는 링크와 그 대상 파일을 함께 보존하세요. 각 앱이 새 위치를 쓰도록 설정하고 필요한 모델을 그곳에서 검증한 뒤에 원본을 지우며, 해당 앱을 쓰는 동안에는 드라이브를 연결해 두세요.
저희가 확인한 범위
2026-09-29에 huggingface_hub 2.0.0과 임시 합성 캐시로 오프라인 검사를 했습니다. 리비전 목록, 전체 ID 표시, 경고 표시, dry-run을 확인했고, 미리보기는 파일을 바꾸지 않았으며, 이전 리비전을 지운 뒤에도 현재 리비전과 공유 데이터는 남았습니다. 실제 모델 다운로드와 추론, 사용자의 캐시, 저장소 사이에 공유된 blob 정리, 드라이브 이전은 검증하지 않았고, 확보되는 용량을 예측하지도 않습니다. 설치된 버전의 명령은 먼저 hf cache --help로 확인하세요.
AskClean은 Mac에서 어디에 공간이 쓰이는지 보여 줍니다. 스캔과 미리보기는 무료이고 AI 분석과 정리에는 Pro가 필요하며, 디스크 정리에서 확인한 항목은 영구 삭제됩니다. 캐시된 리비전과 공유 파일은 Hugging Face CLI로 관리하고, 직접 만든 프로젝트 결과물은 정리 대상에서 빼세요.
다시 만들 수 있는 것과 보관해야 할 것
분류마다 따로 확인하세요. 이 표는 보존하거나 복원해야 할 것을 설명할 뿐, 자동으로 삭제할 파일을 표시하지 않습니다.
| 항목 | 확인 위치 | 삭제 전에 확인할 것 |
|---|---|---|
| Hub 저장소 또는 리비전 | hf cache ls --revisions | 선택 범위를 정확히 확인하세요. 복원하려면 다시 내려받아야 하고 같은 저장소에 접근할 수 있어야 합니다. |
| 공유 blob과 스냅샷 | 확인한 Hub 캐시 | 캐시 관리 도구를 사용하세요. 리비전끼리, 일부 구조에서는 저장소끼리도 같은 파일을 공유합니다. |
| detached 리비전 | hf cache prune --dry-run | 캐시에 이름 붙은 참조가 없어도 프로젝트가 그 리비전을 정확히 지정해 쓸 수 있습니다. |
| 생성된 데이터셋 캐시 | HF_DATASETS_CACHE / Datasets 캐시 설정 | Hub 다운로드와 별개입니다. 다시 만들려면 원본 데이터와 처리 시간이 필요합니다. |
| 직접 만든 체크포인트, 어댑터, 원본 | 프로젝트와 백업 위치 | 원본 작업물을 보관하세요. 캐시 폴더 아래에 있다면 특히 백업에 포함됐는지 확인하세요. |
| Hugging Face 홈과 인증 정보 | HF_HOME | 모델 캐시를 지우려고 홈 디렉터리 전체를 삭제하지 마세요. |
로컬 회귀 테스트에는 아주 작은 합성 캐시를 썼습니다. 그 크기는 벤치마크나 실제 확보 용량의 추정치가 아닙니다.
자주 묻는 질문
Mac에서 ~/.cache/huggingface 폴더를 삭제해도 되나요?
폴더 전체를 버려도 되는 캐시로 보지 마세요. 실제로 쓰는 Hub 캐시를 찾고, 인증 정보와 직접 만든 작업물을 보관한 다음, 설치된 hf cache 명령으로 지울 저장소나 리비전을 미리 확인하세요.
리비전 하나를 지웠는데 표시된 크기보다 적게 확보되는 이유는 무엇인가요?
리비전끼리, 일부 캐시 구조에서는 저장소끼리도 파일을 공유하기 때문입니다. 미리보기의 예상치를 확인하고 삭제 전후의 디스크 사용량과 여유 공간을 비교하세요. 표시된 리비전 크기를 더하면 같은 파일을 여러 번 셀 수 있습니다.
detached 리비전은 쓰지 않는 버전인가요?
꼭 그렇지는 않습니다. 캐시에 이름 붙은 참조가 없어도 프로젝트가 특정 리비전을 지정해 쓸 수 있습니다. prune하기 전에 프로젝트의 요구 사항부터 확인하세요.
hf cache rm이 미세 조정한 모델도 지우나요?
직접 만든 파일이 선택한 캐시 항목 안에 있다면 함께 지워질 수 있습니다. 체크포인트, 어댑터, 수정한 파일은 지울 항목 밖에 두고 백업을 확인하세요. 이름이 cache인 폴더에도 중요한 작업의 유일한 사본이 들어 있을 수 있습니다.
참고 자료