uv sync 사용시 warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance. If the cache and target directories are on different filesystems, hardlinking may not be supported. 경고가 나올 때

이 경고 메시지는 uv가 패키지를 설치할 때 고속 처리를 위해 사용하는 하드링크(Hardlink) 방식을 사용할 수 없어, 데이터를 통째로 복사하는 전체 복사(Full Copy) 방식으로 전환했다는 것을 의미한다.

성능이 조금 떨어질 뿐 설치 자체는 정상적으로 완료되지만, 원인을 해결하거나 설정을 변경하여 경고가 뜨지 않게 조치할 수 있다.

발생 원인

uv는 기본적으로 글로벌 캐시 폴더에 패키지를 다운로드한 뒤, 가상환경(.venv) 폴더로 파일을 연결할 때 하드링크를 사용하여 디스크 공간을 아끼고 속도를 극적으로 높인다. 하지만 다음과 같은 상황에서는 하드링크를 만들 수 없다.

1. 서로 다른 파일 시스템(드라이브): uv 캐시 폴더는 C 드라이브에 있는데, 현재 작업 중인 프로젝트와 가상환경(.venv)은 E 드라이브나 USB 메모리 등에 위치한 경우이다. 하드링크는 물리적으로 동일한 드라이브 안에서만 생성할 수 있다.
2. 네트워크 드라이브 또는 WSL 환경: 네트워크 공유 폴더나 Windows와 WSL(리눅스) 간의 경계를 넘어 파일을 조작할 때 파일 시스템 특성상 하드링크가 제한될 수 있다.

해결 방법

상황에 맞춰 아래 방법 중 하나를 선택하여 해결할 수 있다.

방법 1. 경고 메시지 끄기 (가장 간편함)

서로 다른 드라이브를 사용하는 것이 의도된 환경(예: 프로젝트를 다른 드라이브에서 관리하는 경우)이라면, uv에게 복사 방식을 사용하겠다고 명시하여 경고를 숨길 수 있다.

• PowerShell (Windows) 환경인 경우 터미널에 아래 명령어를 입력한다.유지되게 하려면 PowerShell 프로필 파일($PROFILE)에 위 줄을 추가한다.

  $env:UV_LINK_MODE="copy"
  

• Bash (Linux / WSL / macOS) 환경인 경우 터미널에 아래 명령어를 입력한다.유지되게 하려면 ~/.bashrc 또는 ~/.zshrc 파일 맨 아래에 추가한다.

  export UV_LINK_MODE=copy
  

• 일회성 명령어 사용: 실행할 때마다 옵션을 붙여준다.

  uv sync --link-mode=copy
  

방법 2. 캐시 디렉토리 위치 변경하기 (성능 유지, 추천)

하드링크 고속 기능을 그대로 유지하면서 경고를 없애고 싶다면, uv 캐시 폴더의 위치를 프로젝트가 있는 드라이브(예: E 드라이브) 내부로 강제 지정하면 된다.

• PowerShell (Windows):

  $env:UV_CACHE_DIR="E:\.uv_cache"
  

• Bash (Linux / WSL):

  export UV_CACHE_DIR="/path/to/your/drive/.uv_cache"
  

환경 변수를 설정한 뒤 다시 uv sync를 실행하면 경고 없이 깔끔하게 작동할 것이다.

윈도우즈에선 시스펨 환경변수에 새로운 폴더를 등록하고 리눅스에선 .bashrc 에도 추가한다.