PEP 838 – pyvenv.cfg에 python-version 추가

Author:: Konstantin Schütze <konstin at mailbox.org>
Sponsor:: Alex Waygood <alex.waygood at gmail.com>
Discussions-To:: Pending
Status:: Draft
Type:: Standards Track
Created:: 15-Jul-2026
Python-Version:: 3.16
Post-History:: Pending

Table of Contents

초록
동기
사양
근거
하위 호환성
이 내용을 가르치는 방법
참조 구현
부록: 기존 도구 동작
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP는 가상 환경에서 사용하는 Python 인터프리터를 기록하는 python-version 필드를 pyvenv.cfg에 추가할 것을 제안합니다. 패치 버전 업데이트에 영향을 받지 않도록 주 버전과 부 버전만 기록합니다.

동기

pyvenv.cfg는, PEP 405에 의해 정의된 대로, home와 include-system-site-packages키만 지정합니다. 서로 다른 도구는 가상 환경의 Python 버전에 관한 서로 다른 정보를 기록합니다. Python 3.14.4 최종 버전으로 생성된 가상 환경의 경우 다음과 같습니다.

CPython의 venv 모듈은 '%d.%d.%d' % sys.version_info[:3]로 version 필드를 추가합니다(CPython source). 예: version = 3.14.4입니다.
virtualenv 패키지는 ".".join(str(i) for i in sys.version_info)와 ".".join(str(i) for i in sys.version_info[:3])를 사용하여 version_info 필드와 version 필드를 추가합니다(virtualenv source). 예: version_info = 3.14.4.final.0 및 version = 3.14.4입니다.
uv는 platform.python_version()을 기반으로 version_info 필드를 추가합니다(uv source). 예: version_info = 3.14.4입니다.

이 정보는 다양한 도구에서 사용됩니다. 부록: 기존 도구 동작를 참조하십시오. 일부 도구는 식별을 위해 사용자에게 전체 Python 버전을 표시하려고 하는 반면, 다른 도구는 Python의 주 버전과 부 버전만 필요로 합니다.

한 가지 문제는 version과 version_info의 정의가 서로 다르고 후속 도구에 대한 보장이 없다는 점입니다. 어느 필드도 존재한다는 보장이 없으며, 어느 필드의 세분성도 정의되어 있지 않습니다.

또 다른 문제는 가상 환경 아래에서 실행되는 Python 인터프리터가 변경될 수 있다는 점입니다. Linux 배포판은 일반적으로 단일 배포 버전 내의 정기 업데이트 과정에서 CPython 패치 버전을 업데이트합니다. uv는 upgrading existing Python installations을 지원하며, 그 과정에서 해당 인터프리터를 사용하여 가상 환경도 업그레이드합니다. 패치 버전과 잠재적인 프리릴리스 구성 요소가 포함된 pyvenv.cfg의 version_info 키는 이러한 방식으로 오래되어 유효하지 않게 됩니다.

가상 환경과 상호 작용하는 도구는 버전 세분성에 관한 가정이 위반되면 fail after a Python patch-version upgrade할 수 있습니다. 주 버전과 부 버전만 포함하는 표준화된 필드를 사용하면 이 문제를 피할 수 있습니다.

사양

pyvenv.cfg에 새로운 python-version 필드를 추가합니다. 이 필드는 3.16과 같이 Python 인터프리터의 주 버전과 부 버전을 나타내는 문자열 값을 포함합니다. 이 값은 f"{sys.version_info[0]}.{sys.version_info[1]}"을 사용하여 얻을 수 있습니다. 가상 환경을 생성하는 도구는 pyvenv.cfg에 python-version을 반드시 기록해야 합니다. version 또는 version_info를 읽는 것은 권장되지 않습니다.

Python 인터프리터는 python-version이 일치하지 않는 가상 환경에서 실행을 거부할 수 있습니다.

근거

python-version 키는 아직 알려진 어떤 도구에서도 (GitHub 코드 검색) 사용되지 않으므로, 기존 키 중 어느 것이든 읽는 도구의 손상을 방지합니다. 주 버전과 부 버전만 지정하면, 기반 Python 인터프리터가 한 패치 릴리스에서 다른 패치 릴리스로 업데이트되더라도 값이 최신 상태로 유지됩니다.

이 PEP는 기반 Python 인터프리터가 다른 부 버전으로 업데이트되어 python-version이 오래된 상태가 되는 경우를 처리하지 않습니다. 이는 한 Linux 배포판 버전에서 다른 버전으로 업그레이드할 때 발생할 수 있습니다. 이러한 업데이트는 CPython의 불안정한 C API를 사용하는 모든 패키지를 손상시키며 pyvenv.cfg에 값을 기록하는 다른 방식으로는 해결할 수 없습니다. 가상 환경을 새로 생성하고, 새 Python 버전에 맞게 의존성을 해결한 후, 적절한 패키지를 설치해야만 해결할 수 있습니다. 인터프리터 시작 중 검사를 수행하면 임포트 시점이나 런타임에 원인을 파악하기 어려운 오류가 발생하는 것을 방지하고, 사용자에게 문제를 알릴 수 있습니다.

사용자에게 정확한 Python 버전 정보를 표시하기 위해 도구는 python-version 값을 표시하거나, 전체 Python 버전이 필요한 경우 인터프리터에서 sys.version_info를 조회할 수 있습니다. 이때 가상 환경 인터프리터 또는 기반 실행 파일이 변경되면 해당 정보가 무효화됩니다. 이 PEP는 특정 도구 동작을 요구하지 않으며 기존 패턴을 금지하지도 않습니다. 이 PEP의 목표는 정확하고 복원력 있는 구현에 필요한 정보를 제공하는 것입니다.

uv
virtualenv
venv의 python/cpython#154378
선택적 CPython 시작 검사는 python/cpython#154381에 포함되어 있습니다.

부록: 기존 도구 동작

도구가 버전 값을 구문 분석하는 방식의 일부 목록은 다음과 같습니다.

ty는 점으로 구분된 값을 분할한 후 주 버전과 부 버전 구성 요소만 구문 분석하고 나머지 구성 요소는 무시합니다 (ty 소스). Ty에는 Python의 주 버전과 부 버전만 필요합니다.
VS Code Python 확장은 두 필드를 모두 구문 분석하며 3.9.0.final.0과 같은 virtualenv 스타일 값도 별도로 처리합니다. 두 필드가 모두 있으면 가장 구체적인 버전을 선택합니다 (VS Code 소스). VS Code는 식별을 위해 사용자에게 전체 Python 버전을 표시합니다.
Microsoft Python Environment Tools는 두 필드 모두에 최소 세 개의 숫자 구성 요소를 요구한 후, 처음 두 구성 요소를 구문 분석합니다 (Python Environment Tools 소스). 해당 uv 전용 구문 분석기는 version_info만 저장합니다 (Python Environment Tools uv 소스). VS Code는 식별을 위해 사용자에게 전체 Python 버전을 표시합니다.
pre-commit은 점으로 결합한 sys.version_info 구성 요소와 version_info를 비교합니다. (pre-commit 소스, 상태 검사 소스). 이로 인해 실패가 발생했습니다: uv와 pre-commit이 가상 환경 최신 상태 검사에 대해 서로 다른 결과를 냈습니다.
Jute는 version_info를 (Jute source) 읽습니다. Jute는 식별을 위해 사용자에게 전체 Python 버전을 표시합니다.
MediaHarbor는 version의 처음 두 구성 요소를 구문 분석합니다 (MediaHarbor source).
Jac는 version의 처음 두 구성 요소를 구문 분석합니다 (Jac source).

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.