uv 0.13.0 업그레이드: Python 기본값과 constraints 변경 점검
uv 0.13.0의 Python 선택, constraints 해시와 editable 처리, 경로 해석 및 캐시 변경을 확인하고 CI와 로컬 환경의 대응 방식을 정한다.
2026-10-19
Python 기본값 변경이 영향을 주는 환경부터 찾는다
uv 0.13.0으로 올린 뒤 Python 3.14가 계속 선택되는 로컬 환경에서도, 적합한 인터프리터가 없는 CI에서는 Python 3.15가 다운로드될 수 있다. 기본 stable 버전 변경은 설치된 Python을 일괄 교체하는 동작이 아니다. 버전을 요청하거나 고정했는지, 호환되는 인터프리터가 이미 있는지를 함께 확인해야 한다.
이 글의 버전 기준은 **astral-sh/uv 0.13.0 (2026-10-09), 직전 0.12.24 (2026-10-08)**이다. uv 0.13.0 공식 릴리스노트는 대부분의 사용자가 수정 없이 업그레이드할 수 있을 것으로 예상하면서도, 기본 Python과 입력 파일 해석에 관한 breaking change를 명시한다.
기본 stable Python은 3.14에서 3.15로 바뀌었다. 다음처럼 버전을 지정하지 않고 Python을 설치하는 호출이 직접적인 점검 대상이다.
uv python install
uv venv는 이미 설치된 호환 Python 3.14를 계속 사용할 수 있다. 반면 적합한 인터프리터가 없고 자동 다운로드가 활성화되어 있으면 uv venv나 uvx python은 이제 Python 3.15를 다운로드할 수 있다.
아래 흐름은 기존 인터프리터를 사용할 수 있는 환경과 기본 다운로드 버전의 영향을 받는 환경을 가르는 조건을 보여 준다.
Python 3.14를 유지해야 한다면 실행 환경에 우연히 설치되어 있는 버전에 기대지 말고 명시적으로 요청한다.
uv venv --python 3.14
프로젝트에서는 다음 명령으로 .python-version에 버전을 기록할 수 있다.
uv python pin 3.14
업그레이드 검증에는 기존 로컬 환경뿐 아니라 적합한 Python이 없는 환경도 포함한다. 그래야 설치된 인터프리터의 재사용이 기본값 변경을 가리고 있는지 확인할 수 있다.
constraints의 해시 지시자는 설치 전체를 바꾼다
requirements 파일에서 -c로 포함한 constraints 파일에 --require-hashes가 있다면, uv 0.13.0에서는 그 지시자가 적용된다. 이전에는 이 위치의 지시자를 무시했지만, 이제는 설치에 포함되는 모든 요구사항에 해시가 필요하다. 그 결과 이전 버전에서 성공한 설치도 해시가 빠진 요구사항 때문에 실패할 수 있다.
확인할 곳은 실행 명령에 직접 적힌 옵션만이 아니다. requirements 파일이 포함하는 constraints 파일까지 열어 --require-hashes가 있는지 확인해야 한다. 지시자가 발견되면 constraints에 적힌 항목만 검사해서는 부족하다. 설치 대상 전체에서 해시 누락 여부를 확인한다.
해시 검사가 의도한 정책이라면 빠진 해시를 추가한다. 의도하지 않은 검사라면 포함된 constraints 파일에서 지시자를 제거한다. 지시자를 유지한 채 적용만 끄는 옵트아웃은 제공되지 않는다.
다음 그림은 constraints 내부의 지시자가 그 파일의 항목에만 머물지 않고 설치 대상 전체에 영향을 주는 범위를 나타낸다.
이 변경과 빌드 의존성의 해시 검사는 구분해야 한다. 이번 릴리스에는 전이 의존성을 포함한 빌드 의존성에 해시를 요구하는 --require-build-hashes도 추가됐지만, 이는 preview 기능이다. 포함된 constraints의 기존 --require-hashes를 이제 적용한다는 변경과 같은 항목으로 취급하면 점검 범위가 흐려진다.
editable과 파일 경로는 입력을 고쳐야 한다
같은 constraints 파일에서 -e도 찾아야 한다. requirements 파일이 -c로 포함한 constraints 안의 editable 요구사항은 이전에 조용히 무시됐지만, 이제는 오류가 된다.
이 동작에는 옵트아웃이 없다. editable 요구사항을 -r로 전달하는 requirements 파일로 옮기거나, 직접 --editable로 전달해야 한다. 해시 변경과 달리 값을 보충해서 해결하는 문제가 아니라, 요구사항을 전달하는 위치를 바꾸는 문제다.
파일 경로를 받는 옵션도 확인한다. --constraint, --override, --exclude, --build-constraint의 값은 이제 각각 하나의 경로로 해석된다. 이전에는 따옴표 안에 있어도 공백을 기준으로 나눴지만, 새 동작은 공백을 포함한 파일 경로를 허용한다.
여러 파일을 전달하려고 다음처럼 묶어 두었다면 옵션을 반복하는 형태로 바꾼다. 릴리스노트의 교체 예시는 다음과 같다.
기존 표현:
-c "a.txt b.txt"
변경할 표현:
-c a.txt -c b.txt
이 규칙을 환경변수까지 확대해서 해석하지는 말아야 한다. UV_CONSTRAINT, UV_OVERRIDE, UV_EXCLUDE, UV_BUILD_CONSTRAINT의 공백으로 구분한 목록은 계속 지원된다.
입력 점검에서는 아래 항목을 함께 비교하면 수정 위치와 해결 방법을 구별하기 쉽다.
| 점검 대상 | uv 0.13.0에서의 동작 | 적용할 수정 |
|---|---|---|
포함된 constraints의 --require-hashes |
설치 대상 전체에 해시 요구 | 누락 해시 추가 또는 의도하지 않은 지시자 제거 |
포함된 constraints의 -e |
오류로 거부 | -r로 전달하는 requirements 파일이나 직접 --editable로 이동 |
| 파일 옵션 값의 공백 | 값 하나를 경로 하나로 해석 | 여러 파일이면 옵션 반복 |
| 관련 환경변수의 공백 목록 | 목록 지원 유지 | 파일 옵션과 구분해서 점검 |
캐시 미스와 가상환경 변경은 별도로 확인한다
업그레이드 뒤 의존성을 다시 다운로드하거나 빌드하더라도, 그것만으로 설치 입력이 잘못됐다고 판단할 수는 없다. uv 0.13.0은 성능 개선을 위해 여러 캐시 엔트리의 형식을 변경했다. 이전 버전의 일부 엔트리를 재사용할 수 없어 재다운로드나 재빌드가 발생할 수 있다.
릴리스노트는 이를 breaking change로 분류하지 않는다. 여러 uv 버전이 같은 캐시 디렉터리를 안전하게 공유하는 것도 계속 가능하다. 따라서 캐시 재사용 여부와 requirements 해석 오류를 분리해서 관찰해야 한다. 업그레이드 후 실행 시간을 비교할 때도 재다운로드·재빌드가 있었는지 함께 기록하는 편이 판단에 도움이 된다. 자료에는 그 비용을 예측할 수 있는 시간이나 비율은 제시되어 있지 않다.
가상환경에서는 Python 3.10 이상에 넣던 distutils 시작 패치가 제거된다. 이전에는 _virtualenv.py와 _virtualenv.pth를 모든 새 가상환경에 설치해 distutils 설정이 설치 경로를 바꾸지 못하도록 했다. Python 3.10 이상은 영향을 받는 설정 키를 이미 무시하므로, 이제 해당 파일을 넣지 않아 Python 시작 오버헤드를 줄인다.
적용 경계는 가상환경 생성 시점과 Python 버전이다.
- Python 3.10 이상으로 만드는 새 가상환경에는 패치 파일을 넣지 않는다.
- Python 3.9 이하에서는 패치를 유지한다.
- 기존 가상환경은 자동으로 수정하지 않는다.
기존 환경에서 패치를 제거하려면 Python 3.10 이상으로 환경을 다시 만들어야 한다. 동작을 되돌리는 옵트아웃은 없으며, 이번 변경으로 no-distutils-patch preview 기능이 안정화됐다.
다음 비교는 uv 업그레이드만으로 달라질 수 있는 캐시 재사용과, 환경 재생성이 있어야 바뀌는 기존 가상환경의 차이를 보여 준다.
Windows ARM64에서는 Python 버전과 아키텍처를 함께 고른다
Windows ARM64를 사용한다면 Python 버전만 고정했는지, 아키텍처도 의도대로 선택되는지 확인한다. 이전 ARM64 빌드의 uv는 네이티브 wheel 지원이 제한적이어서 에뮬레이션된 x86_64 Python을 우선했다. 이제는 Python 버전 전반에서 네이티브 ARM64인 aarch64 인터프리터를 우선한다.
네이티브 인터프리터가 없으면 x86_64, 그다음 32비트 x86으로 폴백한다. 기존 x86_64 선택을 유지해야 하는 환경에서는 UV_PYTHON_ARCH=x86_64를 설정하거나 cpython-3.14-windows-x86_64처럼 아키텍처를 명시할 수 있다. setup-uv를 사용한다면 python-arch: x86_64로 지정할 수 있다.
이 항목은 기본 Python 3.15 전환과 별개의 선택 규칙이다. Windows ARM64에서 업그레이드 결과를 비교할 때는 선택된 Python 버전과 아키텍처를 함께 확인해야 어느 변경의 영향을 받았는지 구분할 수 있다.
아카이브와 빌드 출력 경로도 검증한다
uv 0.13.0은 tar 아카이브 처리의 기본 구현을 astral-tokio-tar에서 tar-codec으로 바꿨다. 적용 대상에는 tar 압축 해제, uv_build의 소스 배포본 생성, uv publish의 메타데이터 읽기가 포함된다.
tar-codec은 아카이브를 읽을 때 더 엄격하게 검증한다. 이전에 받아들였던 하드 링크나 지원하지 않는 tar 확장이 든 아카이브를 거부할 수 있다. 따라서 기존 소스 배포본을 읽는 과정이 업그레이드 후 실패한다면 아카이브 내용도 점검 대상이다.
배포본을 만드는 쪽에서는 결과물의 바이트와 해시가 달라질 수 있다. uv_build로 만든 소스 배포본을 비교할 때 이 변경을 고려해야 한다. 기존 tar 구현을 사용해야 한다면 UV_LEGACY_TAR_BACKEND=1로 옵트아웃할 수 있다. 이번 변경은 tar-codec preview 기능의 안정화이기도 하다.
빌드 출력 디렉터리에는 별도의 검증이 추가됐다. uv build --clear는 출력 디렉터리가 프로젝트나 입력 소스 배포본을 포함하면, 빌드 출력을 지우기 전에 거부한다. 심볼릭 링크를 거쳐 같은 위치에 도달하는 경로도 검사한다.
이 오류가 발생하면 빌드 소스를 포함하지 않는 출력 디렉터리를 선택하거나 --clear를 생략한다. 아카이브 읽기 오류와 출력 경로 거부는 해결 방법이 다르므로, 빌드 실패를 모두 tar 구현 변경으로 묶어서 처리해서는 안 된다.
uv build backend 설정 자체에는 breaking change가 없다. 다만 [build-system]에서 uv_build 버전의 상한을 두었다면 0.13을 허용하도록 갱신할 수 있다. 릴리스노트가 제시한 버전 범위는 다음과 같다.
uv_build>=0.13.0,<0.14
업그레이드 검증은 실행 환경과 입력 파일을 맞춰 진행한다
CI와 로컬에서 같은 결과를 기대한다면 먼저 Python 요청·고정 여부를 맞춘다. 기존 인터프리터를 재사용하는 로컬 결과만으로, 적합한 인터프리터가 없는 CI의 다운로드 동작까지 확인했다고 볼 수는 없다.
그다음 실제 설치에 쓰는 requirements와 포함된 constraints를 확인한다. 해시 지시자는 설치 전체의 해시 누락을 점검하고, editable 항목은 전달 위치를 바꾸며, 여러 파일을 묶은 옵션은 반복 옵션으로 고친다. 이 항목들은 캐시 재생성으로 해결되는 문제가 아니다.
마지막으로 사용 중인 기능에 맞춰 Windows ARM64의 아키텍처, 기존 가상환경의 패치, tar 아카이브와 빌드 출력 경로를 확인한다. 대응 수단은 변경마다 다르다.
| 변경 | 기존 동작을 유지하거나 대응하는 방법 | 제한 |
|---|---|---|
| 기본 stable Python 3.15 | Python 3.14 명시 또는 프로젝트 pin | 설치된 호환 인터프리터는 계속 사용 가능 |
| constraints 해시 적용 | 해시 추가 또는 지시자 제거 | 지시자를 둔 채 옵트아웃 불가 |
| constraints editable 거부 | requirements 파일 또는 직접 옵션으로 이동 | 옵트아웃 불가 |
| 파일 옵션의 단일 경로 해석 | 여러 파일이면 옵션 반복 | 관련 환경변수의 공백 목록은 유지 |
| Windows ARM64 네이티브 우선 | 아키텍처 명시 | 네이티브가 없으면 폴백 |
| distutils 시작 패치 제거 | 기존 환경의 패치 제거는 재생성으로 적용 | 옵트아웃 불가, Python 3.9 이하는 유지 |
| 기본 tar 구현 변경 | UV_LEGACY_TAR_BACKEND=1 |
새 구현은 더 엄격하게 검증 |
uv build --clear 경로 거부 |
출력 디렉터리 변경 또는 --clear 생략 |
소스를 포함하는 출력 경로는 거부 |
검증이 끝났다는 기준은 uv 버전이 바뀌었다는 사실만이 아니다. 각 환경에서 의도한 Python이 선택되고, 실제 설치 입력이 새 규칙을 통과하며, 사용하는 빌드·배포 경로까지 실행되는지를 확인해야 한다. 재다운로드나 재빌드는 그 과정에서 별도로 기록할 관찰 항목이다.