파이썬 버전¶
파이썬 버전은 파이썬 인터프리터(즉, python 실행 파일), 표준 라이브러리, 그리고 기타 지원 파일로 구성된다.
관리형과 시스템 Python 설치¶
시스템에 이미 Python이 설치되어 있는 경우가 흔하므로, uv는 Python 버전 탐색을 지원한다. 또한 uv는 Python 버전 설치도 직접 수행할 수 있다. 이 두 가지 유형의 Python 설치를 구분하기 위해, uv는 자체적으로 설치한 Python 버전을 관리형 Python 설치로, 그 외의 모든 Python 설치를 시스템 Python 설치로 구분한다.
Note
uv는 운영체제에 의해 설치된 Python 버전과 다른 도구에 의해 설치 및 관리되는 Python 버전을 구분하지 않는다. 예를 들어, pyenv로 관리되는 Python 설치도 uv에서는 시스템 Python 버전으로 간주한다.
특정 Python 버전 요청하기¶
대부분의 uv 커맨드에서 --python 플래그를 사용해 특정 Python 버전을 요청할 수 있다. 예를 들어, 가상 환경을 생성할 때 다음과 같이 입력한다:
$ uv venv --python 3.11.6
uv는 Python 3.11.6이 시스템에 있는지 확인하고, 필요한 경우 다운로드 및 설치를 진행한 후 해당 버전으로 가상 환경을 생성한다.
다음과 같은 Python 버전 요청 형식을 지원한다:
<version>예:3,3.12,3.12.3<version-specifier>예:>=3.12,<3.13<implementation>예:cpython또는cp<implementation>@<version>예:cpython@3.12<implementation><version>예:cpython3.12또는cp312<implementation><version-specifier>예:cpython>=3.12,<3.13<implementation>-<version>-<os>-<arch>-<libc>예:cpython-3.12.3-macos-aarch64-none
또한, 특정 시스템 Python 인터프리터를 다음과 같은 방식으로 요청할 수 있다:
<executable-path>예:/opt/homebrew/bin/python3<executable-name>예:mypython3<install-dir>예:/some/environment/
기본적으로 uv는 시스템에서 Python 버전을 찾지 못할 경우 자동으로 다운로드한다. 이 동작은 python-downloads 옵션을 통해 비활성화할 수 있다.
파이썬 버전 파일¶
.python-version 파일은 기본 파이썬 버전 요청을 생성하는 데 사용할 수 있다. uv는 작업 디렉토리와 그 상위 디렉토리에서 .python-version 파일을 검색한다. 이전에 설명한 요청 형식 중 어떤 것이든 사용할 수 있지만, 다른 도구와의 호환성을 위해 버전 번호를 사용하는 것을 권장한다.
현재 디렉토리에 .python-version 파일은 uv python pin 커맨드로 생성할 수 있다.
.python-version 파일 검색은 --no-config 옵션으로 비활성화할 수 있다.
uv는 프로젝트나 작업 공간 경계를 넘어서는 .python-version 파일을 검색하지 않는다.
파이썬 버전 설치하기¶
uv는 macOS, Linux, Windows에서 사용 가능한 CPython과 PyPy 배포판 목록을 제공한다.
Tip
기본적으로 uv python install 명령어를 사용하지 않아도 필요한 파이썬 버전이 자동으로 다운로드된다.
특정 버전의 파이썬을 설치하려면:
$ 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
로컬 인터프리터를 요청하는 파일 경로와 같은 형식을 제외한 모든 파이썬 버전 요청 형식을 지원한다.
기본적으로 uv python install은 관리되는 파이썬 버전이 설치되어 있는지 확인하거나 최신 버전을 설치한다. .python-version 파일이 존재하면, uv는 파일에 명시된 파이썬 버전을 설치한다. 여러 파이썬 버전이 필요한 프로젝트는 .python-versions 파일을 정의할 수 있다. 이 파일이 존재하면, uv는 파일에 나열된 모든 파이썬 버전을 설치한다.
Important
사용 가능한 파이썬 버전은 각 uv 릴리스마다 고정된다. 새로운 파이썬 버전을 설치하려면 uv를 업그레이드해야 할 수도 있다.
Python 실행 파일 설치하기¶
Important
Python 실행 파일 설치 기능은 현재 미리보기 단계에 있다. 이는 실험적이며 변경될 수 있다는 의미다.
PATH에 Python 실행 파일을 설치하려면 --preview 옵션을 사용한다:
$ uv python install 3.12 --preview
이 명령어는 요청한 버전의 Python 실행 파일을 ~/.local/bin에 설치한다. 예를 들어 python3.12로 설치된다.
Tip
~/.local/bin이 PATH에 없다면 uv tool update-shell로 추가할 수 있다.
python과 python3 실행 파일을 설치하려면 --default 옵션을 포함한다:
$ uv python install 3.12 --default --preview
Python 실행 파일을 설치할 때, uv는 기존 실행 파일을 덮어쓰지 않는다. 단, 해당 실행 파일이 uv에 의해 관리되는 경우에만 덮어쓴다. 예를 들어 ~/.local/bin/python3.12가 이미 존재한다면 --force 플래그 없이는 덮어쓰지 않는다.
uv는 관리하는 실행 파일을 업데이트한다. 하지만 기본적으로 각 Python 마이너 버전의 최신 패치 버전을 선호한다. 예를 들어:
$ uv python install 3.12.7 --preview # `python3.12`를 `~/.local/bin`에 추가
$ uv python install 3.12.6 --preview # `python3.12`를 업데이트하지 않음
$ uv python install 3.12.8 --preview # `python3.12`를 3.12.8로 업데이트
프로젝트 파이썬 버전 관리¶
uv는 프로젝트 명령어 실행 시 pyproject.toml 파일에 정의된 requires-python에 명시된 파이썬 요구사항을 준수한다. 별도의 버전 요청이 없는 경우, 예를 들어 .python-version 파일이나 --python 플래그를 통해 특정 버전을 지정하지 않으면, 해당 요구사항과 호환되는 첫 번째 파이썬 버전을 사용한다.
설치된 Python 버전 확인하기¶
설치된 Python 버전과 사용 가능한 버전을 나열하려면 다음 명령어를 실행한다:
$ uv python list
기본적으로 다른 플랫폼용 다운로드와 이전 패치 버전은 표시되지 않는다.
모든 버전을 보려면 다음 명령어를 사용한다:
$ uv python list --all-versions
다른 플랫폼용 Python 버전을 보려면 다음 명령어를 실행한다:
$ uv python list --all-platforms
다운로드를 제외하고 설치된 Python 버전만 보려면 다음 명령어를 사용한다:
$ uv python list --only-installed
더 자세한 내용은 uv python list 참조 문서를 확인한다.
파이썬 실행 파일 찾기¶
파이썬 실행 파일을 찾으려면 uv python find 커맨드를 사용한다:
$ uv python find
기본적으로 이 명령어는 사용 가능한 첫 번째 파이썬 실행 파일의 경로를 표시한다. 실행 파일이 어떻게 발견되는지에 대한 자세한 내용은 파이썬 버전 발견 규칙을 참조한다.
이 인터페이스는 다양한 버전 요청 형식도 지원한다. 예를 들어, 3.11 이상 버전의 파이썬 실행 파일을 찾으려면 다음과 같이 입력한다:
$ uv python find >=3.11
기본적으로 uv python find는 가상 환경의 파이썬 버전도 포함한다. 작업 디렉터리나 상위 디렉터리에서 .venv 디렉터리를 발견하거나 VIRTUAL_ENV 환경 변수가 설정된 경우, PATH에 있는 파이썬 실행 파일보다 우선한다.
가상 환경을 무시하려면 --system 플래그를 사용한다:
$ uv python find --system
Python 버전 탐색 방법¶
Python 버전을 검색할 때 다음 위치를 확인한다:
UV_PYTHON_INSTALL_DIR에 설치된 관리형 PythonPATH에 있는python,python3, macOS와 Linux에서python3.x, Windows에서python.exe로 지정된 Python 인터프리터- Windows에서는 Windows 레지스트리와 Microsoft Store에 설치된 Python 인터프리터 중 요청한 버전과 일치하는 것 (
py --list-paths참조)
특정 경우에는 uv가 가상 환경에서 Python 버전을 사용할 수 있다. 이 경우, 위에서 설명한 설치 검색을 수행하기 전에 가상 환경의 인터프리터가 요청과 호환되는지 먼저 확인한다. 자세한 내용은 pip 호환 가상 환경 탐색 문서를 참고한다.
탐색 과정에서 실행 불가능한 파일은 무시한다. 발견된 각 실행 파일은 메타데이터를 조회해 요청한 Python 버전과 일치하는지 확인한다. 조회에 실패하면 해당 실행 파일은 건너뛴다. 실행 파일이 요청을 충족하면 추가 실행 파일을 검사하지 않고 바로 사용한다.
관리형 Python 버전을 검색할 때는 uv가 최신 버전을 우선적으로 선택한다. 시스템 Python 버전을 검색할 때는 첫 번째 호환 버전을 사용하며, 반드시 최신 버전을 선택하지는 않는다.
시스템에서 Python 버전을 찾을 수 없으면, uv는 호환 가능한 관리형 Python 버전 다운로드를 확인한다.
Python 사전 릴리스 버전¶
기본적으로 Python 사전 릴리스 버전은 선택되지 않는다. 요청에 맞는 다른 설치 가능한 버전이 없을 때만 사전 릴리스 버전이 사용된다. 예를 들어, 사전 릴리스 버전만 존재하는 경우에는 해당 버전이 사용되지만, 그렇지 않으면 안정적인 릴리스 버전이 우선적으로 선택된다. 마찬가지로, 사전 릴리스 Python 실행 파일의 경로를 직접 제공한 경우에도 요청에 맞는 다른 Python 버전이 없으므로 사전 릴리스 버전이 사용된다.
사전 릴리스 Python 버전이 사용 가능하고 요청과 일치하는 경우, uv는 안정적인 버전을 대신 다운로드하지 않는다.
자동 Python 다운로드 비활성화¶
기본적으로 uv는 필요한 경우 Python 버전을 자동으로 다운로드한다.
python-downloads 옵션을 사용해 이 동작을 비활성화할 수 있다. 기본값은 automatic으로 설정되어 있으며, manual로 설정하면 uv python install 명령어 실행 시에만 Python 다운로드를 허용한다.
Tip
python-downloads 설정은 지속적인 설정 파일에 정의해 기본 동작을 변경할 수 있다. 또는 --no-python-downloads 플래그를 모든 uv 명령어에 추가해 사용할 수도 있다.
파이썬 버전 선호도 조정¶
기본적으로 uv는 시스템에 설치된 파이썬 버전을 사용하려고 시도하며, 필요한 경우에만 관리되는 인터프리터를 다운로드한다.
python-preference 옵션을 사용해 이 동작을 조정할 수 있다. 기본값은 managed로, 시스템 파이썬 설치보다 관리되는 파이썬 설치를 선호한다. 하지만 여전히 시스템 파이썬 설치가 관리되는 버전을 다운로드하는 것보다 우선순위가 높다.
다음과 같은 대체 옵션을 사용할 수 있다:
only-managed: 관리되는 파이썬 설치만 사용하고, 시스템 파이썬 설치를 전혀 사용하지 않는다.system: 관리되는 파이썬 설치보다 시스템 파이썬 설치를 선호한다.only-system: 시스템 파이썬 설치만 사용하고, 관리되는 파이썬 설치를 전혀 사용하지 않는다.
이 옵션을 통해 uv의 관리되는 파이썬 버전을 완전히 비활성화하거나, 항상 사용하도록 설정해 기존 시스템 설치를 무시할 수 있다.
Note
파이썬 버전 자동 다운로드는 선호도를 변경하지 않고도 비활성화할 수 있다.
파이썬 구현체 지원¶
uv는 CPython, PyPy, GraalPy 파이썬 구현체를 지원한다. 특정 파이썬 구현체가 지원되지 않으면 uv는 해당 인터프리터를 발견하지 못한다.
구현체는 긴 이름이나 짧은 이름으로 요청할 수 있다:
- CPython:
cpython,cp - PyPy:
pypy,pp - GraalPy:
graalpy,gp
구현체 이름 요청은 대소문자를 구분하지 않는다.
지원되는 형식에 대한 자세한 내용은 파이썬 버전 요청 문서를 참고한다.
관리형 Python 배포판¶
uv는 CPython과 PyPy 배포판을 다운로드하고 설치하는 기능을 지원한다.
CPython 배포판¶
파이썬 공식 배포판으로 CPython 바이너리를 제공하지 않기 때문에, uv는 Astral의 python-build-standalone 프로젝트에서 미리 빌드된 배포판을 사용한다. python-build-standalone은 Rye, Mise, bazelbuild/rules_python과 같은 다른 파이썬 프로젝트에서도 사용된다.
uv 파이썬 배포판은 독립적이며, 높은 이식성과 성능을 제공한다. pyenv와 같은 도구에서처럼 소스 코드로부터 파이썬을 빌드할 수 있지만, 이 경우 시스템에 미리 설치된 종속성이 필요하며, PGO와 LTO를 활성화한 최적화된 빌드를 생성하는 과정은 매우 느리다.
이 배포판은 이식성으로 인해 몇 가지 특이한 동작을 보인다. 현재 uv는 Alpine Linux와 같은 musl 기반 리눅스 배포판에 설치하는 기능을 지원하지 않는다. 자세한 내용은 python-build-standalone 특이사항 문서를 참고한다.
PyPy 배포판¶
PyPy 배포판은 PyPy 프로젝트에서 제공한다.