Mac의 Hugging Face 캐시 확인 및 정리

실제 경로와 보관할 데이터 확인하기

일반적인 Hub 캐시는 ~/.cache/huggingface/hub입니다. HF_HUB_CACHE는 저장소 캐시를, HF_HOME은 더 넓은 홈 영역을 지정합니다. HF_HOME이 없으면 XDG_CACHE_HOME이 기본 위치에 영향을 줄 수 있고 앱의 cache_dir로 경로를 바꿀 수도 있습니다. GUI, 터미널, notebook의 환경을 따로 확인하세요. HF_HOME에는 인증 정보도 있을 수 있으므로 전체를 삭제하거나 내용을 공개하지 마세요.

미세 조정한 checkpoint, adapter, tokenizer 변경, 변환 결과, 비공개 데이터, 프로젝트 설정은 다시 받을 수 없을 수 있습니다. 일부 백업 도구는 CACHEDIR.TAG가 있는 캐시를 제외하므로 실제 필요한 파일이 백업됐는지 검증하세요. 복원 방법을 모르면 보관하고 접근 시각만으로 불필요하다고 판단하지 마세요.

전체 ID와 경고 표시하기

캐시를 사용하는 앱, 다운로드, 작업을 중지합니다. hf cache ls --no-truncate 다음에 hf cache ls --revisions --no-truncate --show-warnings를 실행하세요. 검증한 버전은 자세한 경고를 기본적으로 숨깁니다. 사용자 지정 캐시는 모든 명령에 같은 --cache-dir를 사용하세요. 읽기나 구조 문제를 확인하고 사용량과 여유 공간을 기록하되 비공개 저장소 목록은 공유하지 마세요.

미리보기 후 범위를 확정하기

hf cache rm에는 CLI의 전체 ID를 사용하세요. 모델 저장소의 model/ 접두사를 유지하고 디스크의 models-- 폴더 이름으로 바꾸지 마세요. 단일 리비전은 전체 hash와 소속 저장소를 확인합니다. 먼저 --dry-run으로 대상 요약과 예상 용량을 보세요. 파일별 목록은 아니며 저장소 대상은 그 안의 모든 캐시 리비전을 포함합니다.

확인 후 같은 대상과 경로에서 --dry-run만 빼고 확인 프롬프트는 유지하세요. 대상이 바뀌거나 미리보기가 실패하면 삭제를 중단하고 원인을 확인합니다. 삭제된 파일은 휴지통에 들어가지 않으며 복원에는 백업이나 재다운로드 권한이 필요합니다. snapshot 사이, 일부 구조에서는 저장소 사이에도 blob을 공유하므로 캐시 관리 도구에 맡기고 표시된 크기를 단순 합산하지 마세요.

prune과 다른 캐시를 구분하기

검증한 2.0.0의 hf cache prune --dry-run은 detached 리비전과 미완료 다운로드를 미리 보여 줍니다. 이름이 붙은 참조가 없어도 프로젝트가 정확한 리비전을 고정해 사용할 수 있습니다. 항목별로 확인하고 진행 중인 다운로드를 중지하세요. 첫 정리는 하나의 명확한 대상부터 시작하는 편이 좋습니다.

HF_DATASETS_CACHE의 생성 데이터는 Hub 다운로드와 다릅니다. Xet 전송 캐시와 local_dir 출력도 별도로 확인하고 출력 폴더의 직접 수정한 파일을 보관하세요. 분류별 확인 대신 HF_HOME 전체를 삭제하지 마세요.

남겨 둔 모델이 작동하는지 검증하기

같은 방식으로 다시 측정하고 보관한 모델과 리비전을 불러와 결과를 아는 작은 작업을 실행하세요. Python 라이브러리를 임포트하는 것만으로는 충분하지 않습니다. 오프라인 사용이 필요하면 실제로 연결을 끊고 시험합니다. 실패하면 정리를 멈추고 환경, 경로, 파일과 접근 권한 및 공간을 확인한 뒤 복원하세요. 필요한 모델을 계속 지웠다 받는다면 정리 대상이나 용량 계획을 조정해야 합니다.

외장 드라이브로 옮길 때는 공간, 권한, 심볼릭 링크 지원을 확인하고 링크와 실제 대상을 보존하세요. 각 앱에서 새 경로와 필요한 모델을 검증한 뒤 원본을 제거하고 사용 중에는 드라이브 연결을 유지합니다.

검증 범위

2026-09-29에 huggingface_hub 2.0.0과 임시 합성 캐시로 오프라인 검사를 수행했습니다. 목록, 전체 ID, 경고, dry-run을 확인했고 미리보기는 파일을 변경하지 않았으며 이전 리비전 제거 후 현재 리비전과 공유 데이터가 남았습니다. 실제 추론, 사용자 캐시, 저장소 간 공유 blob 정리, 드라이브 이전은 검증하지 않았고 확보 용량을 보장하지 않습니다. 설치된 버전은 hf cache --help로 확인하세요.

삭제 전에 확인할 사항

실제 위치와 용도, 복원 방법부터 확인하세요. 이 표는 자동 삭제 목록이 아니며 확보할 수 있는 용량을 보장하지 않습니다.

자주 묻는 질문