byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Concepts

Python 버전

Python versions · 원문: docs.astral.sh/uv/concepts/python-versions/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

Python 버전은 Python 인터프리터(python 실행 파일), 표준 라이브러리, 지원 파일로 구성됩니다.

관리형 및 시스템 Python 설치

uv는 관리형 Python 설치(uv가 설치한 것)와 시스템 Python 설치(그 외 모든 것)를 구분합니다. 이 도구는 기존 Python 버전을 탐색하는 동시에 사용자가 직접 버전을 설치할 수 있도록 합니다.

참고: uv는 pyenv 등 다른 도구로 설치한 Python 버전을 시스템 설치로 취급합니다.

버전 요청

사용자는 --python 플래그와 다양한 형식으로 특정 Python 버전을 요청할 수 있습니다:

버전 번호: 3, 3.12, 3.12.3
버전 지정자: >=3.12,<3.13
변형: 3.13t (자유 스레드), 3.12.0d (디버그)
구현체: cpython, pypy
전체 사양: cpython-3.12.3-macos-aarch64-none
로컬 경로 또는 실행 파일 이름

예시:

코드 · 명령

$ uv venv --python 3.11.6

Python 버전 파일

.python-version 파일은 기본 Python 버전 요청을 설정합니다. uv는 현재 디렉터리와 상위 디렉터리에서 이 파일을 검색합니다. 다음 명령으로 파일을 생성할 수 있습니다:

코드 · 명령

$ uv python pin

전역 설정의 경우:

코드 · 명령

$ uv python pin --global

Python 버전 설치

uv는 macOS, Linux, Windows용으로 다운로드 가능한 CPython 및 PyPy 배포판을 번들로 제공합니다. 기본적으로 Python 버전은 필요에 따라 자동으로 다운로드됩니다.

설치 예시:

코드 · 명령

$ uv python install 3.12.3
$ uv python install 3.12
$ uv python install '>=3.8,<3.10'
$ uv python install 3.9 3.10 3.11
$ uv python install pypy

중요: 사용 가능한 Python 버전은 uv 릴리스마다 고정됩니다. uv를 업그레이드하면 더 새로운 버전을 사용할 수 있습니다.

Python 실행 파일 설치

uv는 기본적으로 Python 실행 파일을 PATH에 설치합니다(예: Unix의 경우 ~/.local/bin/python3.12). --default 플래그를 추가하면 일반적인 python 및 python3 실행 파일을 설치합니다:

코드 · 명령

$ uv python install 3.12 --default

uv는 자신이 관리하는 실행 파일만 덮어씁니다. 마이너 버전당 최신 패치 버전을 선호합니다:

코드 · 명령

$ uv python install 3.12.7  # Adds python3.12
$ uv python install 3.12.6  # Does not update
$ uv python install 3.12.8  # Updates python3.12

Python 버전 업그레이드

업그레이드는 uv가 관리하는 버전에만 적용되며, 마이너 버전이 아닌 패치 릴리스(예: 3.13.4 → 3.13.5)에만 적용됩니다.

업그레이드 명령:

코드 · 명령

$ uv python upgrade 3.12
$ uv python upgrade

업그레이드된 버전을 사용하는 가상환경은 명시적인 패치 버전으로 생성된 것을 제외하고 자동으로 새 패치 버전으로 업데이트됩니다.

마이너 버전 디렉터리

자동 업그레이드는 심볼릭 링크(Unix) 또는 정션(Windows)을 사용하여 마이너 버전 디렉터리가 특정 패치 버전을 가리키도록 합니다:

코드 · 명령

~/.local/share/uv/python/cpython-3.12-macos-aarch64-none

프로젝트 Python 버전

uv는 pyproject.toml의 requires-python 제약을 준수합니다. .python-version 또는 --python으로 달리 지정하지 않으면 첫 번째 호환 Python 버전이 사용됩니다.

사용 가능한 Python 버전 보기

설치된 버전과 사용 가능한 버전을 나열합니다:

코드 · 명령

$ uv python list
$ uv python list 3.13
$ uv python list pypy

옵션: - --all-versions: 이전 패치를 포함한 모든 버전 표시 - --all-platforms: 다른 플랫폼용 버전 표시 - --only-installed: 설치된 버전만 표시

Python 실행 파일 찾기

코드 · 명령

$ uv python find
$ uv python find '>=3.11'
$ uv python find --system

기본적으로 가상환경을 먼저 검색합니다. --system을 사용하면 가상환경을 무시합니다.

Python 버전 탐색

uv는 다음 위치를 순서대로 확인합니다:

UV_PYTHON_INSTALL_DIR의 관리형 Python 설치
PATH의 python, python3, python3.x(macOS/Linux) 또는 python.exe(Windows)
Windows 레지스트리 및 Microsoft Store Python 인터프리터

실행 불가능한 파일은 무시됩니다. 각 실행 파일은 호환성을 확인하기 위해 메타데이터를 조회합니다. uv는 더 새로운 관리형 버전을 선호하지만 첫 번째로 호환되는 시스템 버전을 사용합니다.

Python 프리릴리스

프리릴리스는 기본적으로 선택되지 않지만, 안정적인 릴리스가 요청과 일치하지 않으면 사용됩니다. 프리릴리스 경로가 명시적으로 제공되면 사용됩니다.

자유 스레드 Python

uv는 CPython 3.13+ 이상에서 자유 스레드(free-threaded) Python 변형을 지원합니다. Python 3.13의 경우 명시적으로 선택해야 합니다:

코드 · 명령

$ uv python install 3.13t
$ uv python install 3.13+freethreaded

Python 3.14+에서는 GIL 활성화 빌드가 기본적으로 여전히 선호되지만, 자유 스레드 변형도 허용됩니다. +gil 변형으로 GIL 활성화를 강제할 수 있습니다.

디버그 Python 변형

디버그 빌드(더 느리고 어설션 활성화)는 다른 일치 항목이 없거나 명시적으로 요청된 경우에만 선택됩니다:

코드 · 명령

$ uv python install 3.13d
$ uv python install 3.13+debug

참고: uv의 디버그 빌드는 일반적으로 디버그 심볼이 제거되어 있습니다. 이 변형은 C 수준 디버깅을 위해 심볼을 유지합니다.

자동 Python 다운로드 비활성화

python-downloads 설정으로 자동 다운로드를 제어합니다:

코드 · 명령

--no-python-downloads

manual로 설정하면 uv python install 중에만 다운로드를 허용합니다.

관리형 Python 버전 요구 또는 비활성화

코드 · 명령

$ uv python list --managed-python
$ uv python list --no-managed-python

영구적인 동작을 위해 설정 파일에서 python-preference 설정을 사용합니다.

Python 버전 선호도 조정

python-preference 설정 옵션:

managed (기본값): 시스템보다 관리형 선호, 다운로드보다 시스템 선호
only-managed: 관리형 버전만 사용
system: 관리형보다 시스템 선호
only-system: 시스템 버전만 사용

Python 구현체 지원

지원 구현체: CPython, PyPy, Pyodide, GraalPy.

이름(전체/약어, 대소문자 구분 없음): - CPython: cpython, cp - PyPy: pypy, pp - GraalPy: graalpy, gp - Pyodide: pyodide

관리형 Python 배포판

CPython 배포판

uv는 Astral의 python-build-standalone 프로젝트에서 사전 빌드된 배포판을 사용합니다. 이 배포판은 자급자족적이고 이식 가능하며 성능이 우수하지만 이식성 관련 특이점이 있습니다.

PyPy 배포판

PyPy 배포판은 PyPy 프로젝트에서 제공됩니다. PyPy는 현재 Python 3.11까지만 지원합니다.

Pyodide 배포판

Pyodide 프로젝트의 Pyodide 배포판은 WebAssembly/Emscripten으로 포팅된 CPython을 제공합니다.

aarch64에서의 투명한 x86_64 에뮬레이션

macOS(Rosetta 2)와 Windows(WoA 에뮬레이션) 모두 aarch64에서 x86_64 바이너리 실행을 지원합니다. uv 또는 Python 중 하나가 에뮬레이션으로 실행될 수 있지만, 패키지는 Python 아키텍처와 일치해야 합니다.

Windows 레지스트리 등록

관리형 Python 버전은 PEP 514에 따라 Windows 레지스트리에 등록됩니다. 설치 후 py 런처를 사용합니다:

코드 · 명령

$ uv python install 3.13.1
$ py -V:Astral/CPython3.13.1

제거 시 레지스트리 항목이 삭제됩니다.

원문(영어): https://docs.astral.sh/uv/concepts/python-versions/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/concepts/python-versions/

문서 이동

‹ 도구 설정 파일 › · 전체 목차