Python 설치하기

시스템에 Python이 이미 설치되어 있다면, uv가 별도의 설정 없이 기존 Python 버전을 감지하고 사용한다. 하지만 uv는 Python 버전을 직접 설치하고 관리할 수도 있다. uv는 필요한 경우 자동으로 Python 버전을 다운로드한다. 따라서 시작하기 전에 Python을 따로 설치할 필요가 없다.

시작하기

최신 Python 버전을 설치하려면 다음 명령어를 실행한다:

$ uv python install

Note

Python은 공식적으로 배포 가능한 바이너리를 제공하지 않는다. 따라서 uv는 Astral의 python-build-standalone 프로젝트에서 제공하는 배포판을 사용한다. 자세한 내용은 Python 배포판 문서를 참고한다.

Python이 설치되면 uv 커맨드에서 자동으로 사용된다.

Important

uv로 Python을 설치하면 전역적으로 사용할 수 없다(즉, python 커맨드로 접근할 수 없다). 이 기능은 현재 미리보기 상태다. 자세한 내용은 Python 실행 파일 설치 문서를 참고한다.

uv run을 사용하거나 가상 환경을 생성하고 활성화하여 python을 직접 사용할 수 있다.

특정 버전 설치하기

특정 Python 버전을 설치하려면:

$ uv python install 3.12

여러 Python 버전을 설치하려면:

$ uv python install 3.11 3.12

PyPy와 같은 대체 Python 구현체를 설치하려면:

$ uv python install pypy@3.10

더 자세한 내용은 python install 문서를 참고한다.

파이썬 재설치

uv로 관리되는 파이썬 버전을 재설치하려면 --reinstall 옵션을 사용한다. 예를 들어:

$ uv python install --reinstall

이 명령어를 실행하면 이전에 설치했던 모든 파이썬 버전을 다시 설치한다. 파이썬 배포판에는 지속적으로 개선 사항이 추가되기 때문에, 파이썬 버전이 변경되지 않더라도 재설치를 통해 버그를 해결할 수 있다.

Python 설치 목록 확인

사용 가능한 Python 버전과 설치된 버전을 확인하려면 다음 명령어를 실행한다:

$ uv python list

더 자세한 내용은 python list 문서를 참고한다.

파이썬 자동 다운로드

uv를 사용하기 위해 파이썬을 따로 설치할 필요는 없다. 기본적으로 uv는 필요한 파이썬 버전을 자동으로 다운로드한다. 예를 들어, 다음 명령어는 파이썬 3.12가 설치되지 않았을 경우 자동으로 다운로드한다:

$ uvx python@3.12 -c "print('hello world')"

특정 파이썬 버전을 요청하지 않더라도, uv는 필요할 때 최신 버전을 다운로드한다. 예를 들어, 시스템에 파이썬이 전혀 설치되어 있지 않다면, 다음 명령어는 새로운 가상 환경을 만들기 전에 파이썬을 설치한다:

$ uv venv

Tip

파이썬 다운로드 시점을 직접 제어하고 싶다면, 파이썬 자동 다운로드를 쉽게 비활성화할 수 있다.

기존 Python 버전 사용하기

uv는 시스템에 설치된 Python 버전을 자동으로 사용한다. 이 동작을 위해 별도의 설정이 필요하지 않다. uv는 커맨드라인 실행 요구 사항을 만족하는 경우 시스템 Python을 기본으로 사용한다. 자세한 내용은 Python 버전 탐색 문서를 참조한다.

uv가 반드시 시스템 Python을 사용하도록 강제하려면 --python-preference only-system 옵션을 추가한다. 더 자세한 정보는 Python 버전 우선순위 설정 문서에서 확인할 수 있다.

다음 단계

uv python에 대해 더 알아보려면 Python 버전 개념 페이지와 명령어 레퍼런스를 참고한다.

또는 스크립트 실행 방법과 uv를 사용해 Python을 실행하는 방법을 계속해서 알아본다.