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에 추가할 것을 제안합니다. 패치 버전이 업데이트되어도 영향을 받지 않도록 메이저 버전과 마이너 버전만 기록합니다.

동기

PEP 405에서 정의한 pyvenv.cfg는 home과 include-system-site-packages 키만 지정합니다. 도구마다 가상 환경의 Python 버전에 관해 기록하는 정보가 서로 다릅니다. Python 3.14.4 정식 버전으로 생성한 가상 환경의 경우는 다음과 같습니다:

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

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

한 가지 문제는 version과 version_info의 정의가 서로 다르고, 다운스트림 도구를 위한 보장이 없다는 점입니다. 두 필드 중 어느 것도 존재가 보장되지 않으며, 어느 필드의 세분성도 정의되어 있지 않습니다.

또 다른 문제는 가상 환경의 기반이 되는 Python 인터프리터가 바뀔 수 있다는 점입니다. Linux 배포판은 하나의 배포판 버전 안에서 이루어지는 정기 업데이트의 일환으로 CPython 패치 버전을 일상적으로 업데이트합니다. uv는 기존 Python 설치 업그레이드를 지원하며, 이 과정에서 해당 인터프리터를 사용하는 가상 환경도 함께 업그레이드합니다. 이런 식으로 패치 버전과 프리릴리스 구성 요소를 포함할 수 있는 pyvenv.cfg의 version_info 키는 낡은 정보가 됩니다.

가상 환경과 상호 작용하는 도구는 버전 세분성에 대한 가정이 깨지면 파이썬 패치 버전 업그레이드 후 실패할 수 있습니다. 메이저 버전과 마이너 버전만 담는 표준화된 필드를 사용하면 이 문제를 피할 수 있습니다.

명세

새로운 python-version 필드가 pyvenv.cfg에 추가됩니다. 이 필드에는 3.16과 같이 Python 인터프리터의 메이저 버전과 마이너 버전을 담은 문자열 값이 들어갑니다. 이 값은 f"{sys.version_info[0]}.{sys.version_info[1]}"로 얻을 수 있습니다. 가상 환경을 생성하는 도구는 반드시(MUST) pyvenv.cfg에 python-version을 기록해야 합니다. version 또는 version_info를 읽는 것은 권장하지 않습니다.

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

근거

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
python/cpython#154378의 venv
python/cpython#154381의 선택적 CPython 시작 검사

부록: 기존 도구의 동작

도구가 버전 값을 파싱하는 방식을 정리한 목록이며, 모든 도구를 망라하지는 않습니다:

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은 version_info를 점으로 연결한 sys.version_info 구성 요소와 비교합니다. (pre-commit source, health-check source). 이로 인해 실패가 발생했습니다. uv와 pre-commit이 가상 환경의 최신 여부 검사에서 서로 다른 판단을 내린 것입니다.
Jute는 version_info를 읽습니다 (Jute 소스). Jute는 식별을 위해 사용자에게 전체 Python 버전을 보여 줍니다.
MediaHarbor는 version의 처음 두 구성 요소를 파싱합니다 (MediaHarbor 소스).
Jac은 version의 처음 두 구성 요소를 파싱합니다 (Jac 소스).

Copyright

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