캐싱

의존성 캐싱

uv는 실행 간 의존성의 재다운로드 및 재빌드를 방지하기 위해 적극적인 캐싱을 구현합니다. 캐싱 방식은 의존성 유형에 따라 다릅니다:

• 레지스트리 의존성 (예: PyPI): uv가 HTTP 캐싱 헤더를 준수합니다.
• 직접 URL 의존성: HTTP 헤더를 따르고 URL로 캐시합니다.
• Git 의존성: 완전히 해석된 커밋 해시를 기반으로 캐시합니다. uv pip compile은 이것들을 특정 커밋에 고정합니다.
• 로컬 의존성: .whl/.tar.gz 파일이나 설정 파일의 마지막 수정 시간을 기반으로 캐시합니다.
• 플랫 인덱스 (--find-links): 변경 불가능한 내용으로 가정하고 파일명으로 캐시합니다.

캐시 관리 옵션

캐시된 데이터를 관리하는 여러 명령이 있습니다:

• uv cache clean — 모든 항목을 제거합니다.
• uv cache clean <package-name> — 특정 패키지를 대상으로 합니다.
• --refresh 플래그 — 캐시된 모든 의존성을 재검증합니다.
• --refresh-package <name> 플래그 — 특정 패키지를 재검증합니다.
• --reinstall 플래그 — 설치된 버전을 무시합니다.

명시적으로 전달된 로컬 디렉터리 의존성(예: uv pip install .)은 항상 재빌드 및 재설치됩니다.

동적 메타데이터

기본적으로 uv는 pyproject.toml, setup.py, setup.cfg, 또는 src 디렉터리가 변경될 때만 로컬 디렉터리 의존성을 재빌드합니다. 이 휴리스틱은 일부 시나리오를 놓칠 수 있습니다.

pyproject.toml의 tool.uv.cache-keys를 통해 사용자 정의 캐시 키를 추가하여 추가 캐시 트리거를 포함할 수 있습니다:

[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true } }]

지원되는 캐시 키 유형: - file — 특정 파일 또는 글로브 패턴 - git — 커밋 해시 및 태그 - env — 환경 변수 - dir — 디렉터리 존재 여부

매 실행마다 특정 패키지를 강제로 재빌드하려면 tool.uv.reinstall-package를 사용합니다.

캐시 안전성

여러 uv 명령이 동시에 안전하게 실행될 수 있습니다. uv의 캐시는 스레드 안전하고 추가 전용으로 설계되었으며, 가상환경에 대한 파일 기반 잠금을 사용합니다. 캐시를 직접 수정하지 마세요.

캐시 지우기

• uv cache clean — 모든 항목을 완전히 제거합니다.
• uv cache clean <package-name> — 특정 패키지를 지웁니다.
• uv cache prune — 이전 uv 버전의 사용되지 않는 항목을 제거합니다.

캐시를 수정하는 작업은 다른 uv 명령이 실행되는 동안 차단됩니다(기본 5분 타임아웃, UV_LOCK_TIMEOUT으로 조정 가능). 적절한 경우 --force를 사용하여 잠금을 건너뜁니다.

CI에서의 캐싱

CI 환경의 경우 uv cache prune --ci를 실행하여 사전 빌드된 휠 및 소스 배포판을 제거하면서 빌드된 휠은 유지합니다. 이는 모든 것을 캐시하는 것보다 빠른 경우가 많습니다. 소스에서 빌드된 휠을 캐시하는 것은 가치 있는 경향이 있으므로 이 전략은 성능의 균형을 맞춥니다.

캐시 디렉터리

uv는 다음 우선순위로 캐시 디렉터리를 선택합니다:

1. 임시 디렉터리(--no-cache가 지정된 경우)
2. --cache-dir, UV_CACHE_DIR, 또는 tool.uv.cache-dir을 통한 사용자 정의 디렉터리
3. 시스템 기본값(예: Unix의 $XDG_CACHE_HOME/uv, Windows의 %LOCALAPPDATA%\uv\cache)

참고: uv는 항상 캐시 디렉터리가 필요합니다. 더 나은 성능을 위해 --no-cache 대신 --refresh를 사용합니다. 캐시는 효율적인 파일 링크를 위해 Python 환경과 동일한 파일 시스템에 있어야 합니다.

캐시 버전 관리

캐시 버킷(휠, 배포판, Git 저장소 등)은 버전이 지정됩니다. 호환성을 깨는 형식 변경은 버전을 증가시켜 호환되지 않는 읽기/쓰기를 방지합니다. 여러 uv 버전이 캐시 디렉터리를 안전하게 공유할 수 있지만, 버전이 다를 때는 항목이 중복될 수 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/cache/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/cache/