Python 기본 버전을 한 단계 올리면서 requires-python은 그대로 두려는 분이라면, 버전 문자열을 바꾸는 것보다 "어떤 파이썬이 실제로 골라지는가"를 먼저 확인해야 한다. 내 개인 라우터 도구를 CPython 3.15 기본으로 옮길 때 막힌 곳은 두 군데였다. Docker 빌드에 쓰던 uv 0.9.0은 3.15를 내려받지 못했고, macOS 개발 장비에서는 uv가 Homebrew의 프레임워크 빌드 3.15를 골라 앱 번들 서명이 깨졌다. 앞의 것은 uv를 digest로 고정해 올려서, 뒤의 것은 uv가 자기가 관리하는 파이썬만 쓰게 설정해서 풀었다. 이 글은 그 전환의 기록과 테스트 리뷰가 잡아낸 약한 단언, 확인하지 못한 부분을 다룬다. 이 글은 작성자의 작업 기록을 바탕으로 Claude 모델이 초안을 작성했다.

무엇을 바꾸고 무엇을 남겼나

이 도구는 Python CLI와 PySide6 기반 GUI로 이루어져 있고, 무거운 계산은 PyO3 확장으로 묶은 Rust 함수가 맡는다. 전환 전 개발 기본값은 .python-version의 3.14였다. pyproject.toml의 requires-python은 >=3.13이었고, 네이티브 확장은 abi3-py313으로 빌드해 확장 하나가 3.13 이상을 모두 받았다. Docker 이미지는 별도로 CPython 3.13.7과 uv 0.9.0 기반 이미지를 쓰고 있었다.

나는 에이전트 하네스에 "Python 3.15로도 올리는 작업"을 맡겼고, 계획 단계에서 방향을 두 갈래로 놓고 비교했다.

  1. requires-python을 >=3.15로 올린다. 3.13과 3.14 사용자를 이유 없이 끊게 되므로 버렸다.
  2. 기본값만 3.15로 바꾸고 >=3.13과 abi3-py313은 유지한다. 이쪽을 골랐다. 되돌리기도 쉽다.

계획 단계에서 미리 확인한 사실도 있다. 3.15 기준으로 의존성을 풀어 보니 Windows x64와 macOS arm64, Linux x86_64는 해결됐다. Linux aarch64에는 3.15용 PySide6-Essentials 휠이 없었다. Docker 이미지는 Qt를 설치하지 않으므로 영향이 없다고 판단해 범위에서 뺐다.

바꾼 파일은 일곱 개다. 목록은 다음과 같다.

  • .python-version: 3.14에서 3.15로
  • Dockerfile: uv 기반 이미지의 태그와 digest, PYTHON_VERSION=3.15.2, 정리 루프의 경로
  • scripts/docker-smoke.sh: 런타임 버전 검사
  • pyproject.toml: [tool.uv] 블록 하나
  • 패키징 테스트 두 파일
  • Docker 문서 한 줄(맡은 경로 밖이라 편차로 기록)

uv 0.9.0이 3.15를 찾지 못한 이유

처음 떠올린 가장 작은 수정은 Docker의 PYTHON_VERSION만 바꾸는 것이었다. 설계 노트에서는 이 안을 두 번째 대안으로 적어 두고 버렸다. 기존 uv 0.9.0 이미지에서 3.15를 요청하면 다음 오류가 났기 때문이다.

== uv 0.9.0
uv 0.9.0
error: No download found for request: cpython-3.15-linux-aarch64-gnu
== uv 0.13.7
uv 0.13.7 (aarch64-unknown-linux-musl)

같은 요청을 uv 0.13.7에서 하면 3.15를 찾았다. uv 문서의 Python versions 페이지에는 이 동작을 설명하는 문장이 있다.

"The available Python versions are frozen for each uv release. To install new Python versions, you may need to upgrade uv."

내 해석은 이렇다. uv가 내려받을 수 있는 파이썬 목록은 uv 릴리스에 묶여 있다. 그래서 새 파이썬 버전으로 갈 때는 파이썬 버전과 uv 버전을 한 묶음으로 올려야 한다. 이번 경우 uv 0.9.0의 목록에는 3.15가 없었던 것으로 보인다. 다만 0.9.0의 내장 목록을 직접 열어 보지는 않았다.

그래서 기반 이미지를 ghcr.io/astral-sh/uv:0.13.7로 올렸다. 태그 뒤에는 docker buildx imagetools inspect로 얻은 멀티 아키텍처 index digest를 붙였다. 파이썬도 3.15.2라는 정확한 패치 버전으로 고정했다. 패치 번호 없는 3.15 태그를 쓰는 세 번째 대안은 이미지가 재현되지 않는다는 이유로 버렸다.

Homebrew 3.15가 서명을 깨뜨린 경로

macOS 번들 빌드에서도 문제가 나왔다. 개발 장비에서 3.15로 uv sync를 하자 uv는 Homebrew가 설치한 프레임워크 빌드 python@3.15를 골랐다. PyInstaller는 이 인터프리터로 번들을 만들면서 Frameworks/python3.15/lib-dynload 구조를 남겼다. 그 뒤 번들 스크립트의 codesign --force --deep가 다음처럼 실패했다.

dist/Router.app: replacing existing signature
dist/Router.app: bundle format unrecognized, invalid, or unsuitable
In subcomponent: .../dist/Router.app/Contents/Frameworks/python3.15

같은 장비에서 uv가 관리하는 독립 실행형 3.15로 다시 빌드하자 번들 생성, 스모크 테스트, 서명 검증이 모두 통과했다. 스모크 테스트 출력은 PASS: router help, PASS: router accounts --json, PASS: router-gui stays up 세 줄이었다. 원인 후보는 이렇게 좁혀졌다. 버전이 같아도 "어느 배포판의 3.15인가"에 따라 번들 안의 디렉터리 구조가 달라졌고, 서명 도구는 그 구조 하나를 번들로 인식하지 못했다.

아래 그림은 같은 uv sync가 어떤 인터프리터를 고르느냐에 따라 두 갈래로 나뉜 흐름을 정리한 것이다.

같은 3.15 uv sync가 두 갈래로 나뉜 것을 비교한 그림이다. 왼쪽 경로에서는 uv가 Homebrew 프레임워크 빌드 python@3.15를 골랐고, PyInstaller가 번들에 Frameworks/python3.15/lib-dynload 구조를 남겼으며, codesign --force --deep 단계에서 실패했다. 오른쪽 경로에서는 uv가 관리하는 독립 실행형 3.15를 썼고, 번들 생성과 스모크 테스트가 PASS 세 줄로 통과했으며, 같은 서명 스크립트로 서명 검증까지 통과했다.
같은 3.15라도 Homebrew 빌드에서는 서명이 실패하고 uv 관리형 빌드에서는 통과했으며, 번들 구조 차이는 원인 후보로 남았다.

Apple의 기술 노트 TN2206은 --deep을 서명 단계에 쓰는 것을 권하지 않는다.

"While the --deep option can be applied to a signing operation, this is not recommended. We recommend that you sign code inside out in individual stages"

같은 노트는 --deep --force가 번들 안의 모든 코드를 강제로 다시 서명한다고 설명한다. 내 번들 스크립트는 바로 이 조합을 쓰고 있었다. 그러니 서명 방식 자체도 개선 후보다. 다만 이번 전환에서는 서명 스크립트를 고치지 않았다. 문제가 생긴 조건이 "Homebrew 프레임워크 파이썬을 골랐을 때"로 좁혀졌고, 관리형 파이썬에서는 같은 스크립트가 통과했기 때문이다. 서명 방식 개선은 이 글의 범위 밖으로 남긴다.

버전 번호가 같아도 어느 배포판의 인터프리터가 골라졌는지에 따라 번들 결과가 달라졌다. 버전 전환은 실제로 골라진 인터프리터로 번들과 서명까지 끝내 봐야 확인된다.

고정 방법은 두 가지를 비교했다.

관리형 파이썬 고정 방법 비교
방법적용 범위판단
release.yml의 env:에 UV_PYTHON_PREFERENCE 지정그 워크플로 작업 하나버림. 로컬 개발과 Windows 작업은 계속 호스트 파이썬을 쓸 수 있다
pyproject.toml의 [tool.uv]에 python-preference = "only-managed"이 프로젝트에서 uv를 쓰는 모든 곳채택
(바꾸지 않음) 기본값 managed시스템에 맞는 파이썬이 있으면 그것을 씀Homebrew 3.15가 골라져 실패한 상태

uv 문서는 기본값 managed에 대해 "system Python installations are still preferred over downloading a managed Python version"이라고 적는다. 관리형을 우선하더라도 아직 내려받지 않았다면 시스템 파이썬이 이긴다는 뜻이다. 내 장비에서 일어난 일이 정확히 그 경우였다. only-managed는 문서 표현으로 "never use system Python installations"이므로 Homebrew 빌드를 아예 후보에서 뺀다.

[tool.uv]
python-preference = "only-managed"

대가도 있다. 첫 uv sync에서 uv가 관리형 3.15를 내려받는다. 네트워크가 없는 장비라면 먼저 uv python install 3.15를 실행해야 한다. 설계 노트에 이 트레이드오프를 그대로 적었다.

테스트 리뷰가 잡은 세 가지 빈틈

이 작업은 Claude 쪽 에이전트가 테스트를 먼저 쓰고, GPT 쪽 리뷰어가 그 테스트를 한 번 검토하는 순서로 진행됐다. 그 전에 계획 검증에서도 한 번 실패했다. 지적은 Docker 스모크 스크립트가 "3.13 이상"만 확인한다는 것이었다. 그러면 3.13이나 3.14로 빌드된 이미지도 통과한다. 그래서 검사를 sys.version_info[:2] == (3, 15)로 정확히 맞추도록 계획을 한 번 고쳤다. 앞으로 버전을 올릴 때마다 이 스크립트를 고쳐야 하지만, 의도한 대가다.

테스트 리뷰는 coverage 5, assertions 4, edge_cases 4로 실패했고 차단 사유 세 가지를 남겼다. 요지는 "단언이 통과해도 원하는 성질이 보장되지 않는다"였다.

테스트 리뷰가 지적한 단언과 실제로 놓치는 경우
처음 단언통과하지만 틀린 경우보완 방향
스모크 스크립트 본문에 sys.version_info[:2] == (3, 15) 문자열이 있는지 확인느슨한 3.14 이상 검사를 남기고 같은 문자열을 주석으로 넣어도 통과3.13, 3.14, 3.15 런타임을 흉내 내 종료 결과를 확인
정리 루프에 리터럴 lib/python3.15가 있는지 확인버전에서 경로를 만들어 내는 올바른 루프를 오히려 실패시킴정리 동작을 보거나 동등한 버전 유래 경로를 허용
uv 태그가 0.13.7이고 digest가 붙어 있는지 확인0.13.7 태그에 예전 0.9.0 digest를 붙여도 통과. Docker는 digest를 따르므로 3.15를 설치하지 못하는 이미지가 쓰인다확인된 태그와 digest 쌍 자체를 단언

세 번째 지적이 가장 아팠다. 이미지를 digest로 고정하는 이유가 재현성인데, 테스트는 "digest가 있다"는 모양만 보고 그 digest가 어떤 이미지를 가리키는지는 보지 않았다. 보완 RED 커밋 두 개로 한 번 고쳤고, 규칙대로 재리뷰는 하지 않았다. 로직 리뷰는 첫 시도가 요청 형식 결함으로 미검토 처리됐고, 두 번째 시도에서 9/8/8/8/8로 통과했다.

관리형 파이썬 고정을 확인하는 test_uv_uses_only_managed_python은 리뷰받은 테스트 묶음 밖에서 추가됐다. 설정 표가 없으면 .get 연쇄가 빈 값을 돌려줘 단언에서 실패하도록 썼다고 기록돼 있다. 이 테스트가 리뷰를 거치지 않았다는 점은 한계로 남긴다.

검증 결과와 수치

최종 결과는 아래와 같다. 모두 당시 실행 기록에서 옮긴 값이고, 이 글을 쓰면서 다시 실행하지는 않았다.

  • pytest 485개 통과
  • macOS 번들, dmg, codesign 통과
  • Docker 이미지 크기 185,585,576 B. 상한 200,000,000 B 안이라 예산은 바꾸지 않았다
  • 릴리스 워크플로를 수동 실행해 Windows와 macOS 작업이 모두 성공
  • develop CI와 승격 검사 통과 뒤 main으로 승격

Windows 번들은 CI 기본 검사에서 만들지 않는다. 그래서 릴리스 워크플로에 이미 있던 수동 실행 트리거를 써서 작업 브랜치에서 gh workflow run release.yml로 확인했다. macOS 번들은 직전 패키징 작업에서 쓰던 명령을 그대로 다시 돌렸다. PyInstaller spec 빌드, 번들 스크립트, 번들 테스트, 스모크 스크립트 순서다. spec 파일은 3.15에서 실제 실패가 관찰될 때만 고치기로 했고, 고칠 일은 생기지 않았다.

Docker 크기는 직전 전환 기록에서 3.13 기준 178,412,686 B였다. 3.15로 바꾼 뒤 7,172,890 B가 늘었다. 두 값은 서로 다른 실행에서 잰 것이라 증가분 전부를 파이썬 버전 차이로 돌릴 수는 없다. uv 기반 이미지도 함께 바뀌었다.

버전 전환 점검 순서

이번 기록에서 다음 전환에 쓸 순서를 뽑으면 이렇다. 실제로 겪은 실패에서 나온 항목만 적었다.

  1. 도구 버전부터 확인한다. 이미지 안의 uv로 새 파이썬을 실제로 요청해 보고, 안 되면 uv를 digest와 함께 올린다.
  2. 플랫폼별 휠을 확인한다. 이번에는 Linux aarch64에 PySide6 휠이 없었다. 그 플랫폼이 Qt를 쓰는지에 따라 영향 여부가 갈린다.
  3. 로컬에서 어떤 인터프리터가 골라지는지 본다. 기본 선호 설정에서는 이미 설치된 시스템 파이썬이 골라질 수 있다.
  4. 번들과 서명을 그 인터프리터로 끝까지 돌린다. 버전 번호가 같아도 배포판이 다르면 결과가 달랐다.
  5. 버전 검사는 "이상"이 아니라 "정확히"로 쓴다. 이전 버전 이미지가 실패해야 검사가 의미를 갖는다.
  6. 테스트가 문자열 존재만 보는지 확인한다. 주석으로 통과할 수 있는 단언은 동작을 보도록 바꾼다.

아래 흐름도는 위 여섯 단계를 순서대로 놓고, 이번에 결과를 가른 번들·서명 단계를 강조한 것이다.

버전 전환 점검 순서를 여섯 단계로 보여 주는 흐름도다. 1단계는 이미지 안의 uv로 새 파이썬을 실제로 요청해 보는 도구 버전 확인이다. 2단계는 Linux aarch64에 PySide6 휠이 없었던 경우처럼 플랫폼별 휠을 확인하는 단계다. 3단계는 시스템 파이썬이 골라질 수 있으니 로컬에서 어떤 인터프리터가 선택되는지 확인한다. 4단계는 번들과 서명을 그 인터프리터로 끝까지 돌리는 단계로, 버전 번호가 같아도 배포판이 다르면 결과가 달라지므로 강조 표시되어 있다. 5단계는 이전 버전 이미지가 실패하도록 버전 검사를 '이상'이 아니라 '정확히'로 쓰는 단계다. 6단계는 테스트가 문자열 존재만 보지 않고 동작을 보도록 단언을 점검하는 단계다.
버전 전환은 도구와 휠부터 실제 인터프리터의 번들 결과, 그리고 그것을 지키는 검사와 테스트까지 차례로 확인해야 안전하다는 것이 이 그림의 요점이다.

관련 글로, CI 실행 환경을 바꿀 때 깨진 지점은 자체 호스팅 러너로 옮기며 CI가 깨진 기록에 정리했다. Windows로 옮기기 전에 줄끝을 LF로 고정한 과정은 .gitattributes 줄끝 고정 기록에 있다. 리뷰어의 지적을 그대로 받아들이지 않고 확인하는 방법은 AI 검증자 지적 확인 글에서 다뤘다. 다른 글은 프로그래밍 카테고리에서 볼 수 있다.

확인하지 못한 것

  • Homebrew 프레임워크 빌드에서 codesign이 정확히 어떤 구조를 거부했는지는 분석하지 않았다. 실패한 하위 구성 요소 경로와 관리형 빌드의 통과까지만 기록돼 있다.
  • uv 0.9.0의 내장 다운로드 목록을 직접 열어 3.15가 빠졌음을 확인하지는 않았다. 오류 메시지와 문서 문장으로 추정한 것이다.
  • Docker 크기 증가분 7,172,890 B의 구성은 나누어 보지 않았다. Docker 문서의 크기 수치 조사는 후속 이슈로 남겼다.
  • only-managed 고정 테스트는 독립 리뷰를 받지 않았다.
  • 서명 스크립트의 --deep --force 사용은 바꾸지 않았다. Apple 권고와 다르다는 점만 확인했다.

기본 버전을 올리는 일은 문자열 하나를 바꾸는 작업처럼 보였다. 하지만 실제로 결과를 가른 것은 그 문자열이 어느 배포판의 어떤 인터프리터로 풀리느냐였다. 다음 버전 전환에서도 같은 질문을 먼저 확인할 생각이다.

자주 묻는 질문

requires-python을 함께 올려야 하나요?

이번 전환에서는 올리지 않았습니다. 기본값만 3.15로 바꾸고 >=3.13과 abi3-py313을 유지해 3.13과 3.14 사용자를 계속 지원했습니다.

uv가 새 파이썬 버전을 찾지 못하면 무엇부터 확인하나요?

uv 버전을 확인합니다. uv 문서에 따르면 설치 가능한 파이썬 목록은 uv 릴리스마다 고정됩니다. 이번에는 uv 0.9.0이 3.15 요청에 "No download found" 오류를 냈고 0.13.7은 찾았습니다.

python-preference를 only-managed로 바꾸면 무엇이 달라지나요?

uv가 시스템에 설치된 파이썬을 후보에서 빼고 자기가 관리하는 파이썬만 씁니다. 이번에는 Homebrew 프레임워크 빌드가 골라지는 것을 막아 codesign 실패를 피했습니다. 첫 동기화 때 다운로드가 필요하고, 오프라인 장비는 미리 설치해야 합니다.

Docker 스모크 검사를 정확한 버전으로 쓰면 불편하지 않나요?

버전을 올릴 때마다 스크립트를 고쳐야 합니다. 그래도 "3.13 이상" 검사는 3.13이나 3.14 이미지도 통과시키므로, 이번 전환이 실제로 적용됐는지 확인하지 못합니다.

참고한 자료