pyenv 기본 사용법
목적
개발하다 보면 프로젝트마다 요구하는 Python 버전이 다른 경우가 생긴다. pyenv는 이런 상황에서 Python 버전을 프로젝트별로 격리하고 관리하는 도구다.
- 시스템 Python을 건드리지 않고 원하는 버전을 설치할 수 있다.
- 프로젝트 폴더마다 다른 Python 버전을 지정할 수 있다.
- python 명령어를 원하는 버전으로 연결할 수 있다.
단, pyenv는 Python 버전만 관리하며 패키지 관리는 담당하지 않는다. 패키지 격리는 venv 또는 uv를 함께 사용한다.
Windows에서는 pyenv를 직접 지원하지 않으며, pyenv-win이라는 별도 포트를 사용한다.
설치
macOS
brew install pyenv
설치 후 ~/.zshrc에 아래 내용을 추가한다.
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
추가 후 적용:
source ~/.zshrc
PowerShell(cmd 아님)에서 아래 명령어로 설치한다.
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
설치 후 PowerShell을 재시작하면 환경변수가 자동으로 적용된다. 적용 여부는 아래 명령어로 확인한다.
pyenv --version
스크립트 실행이 막힌 경우( UnauthorizedAccess ) PowerShell을 관리자 권한으로 열고 아래 명령어를 먼저 실행한다.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Python 버전 설치
macOS와 Windows 모두 동일한 명령어를 사용한다.
# 설치 가능한 버전 목록 확인
pyenv install --list
# 특정 버전 설치
pyenv install 3.12.0
# 설치된 버전 목록 확인
pyenv versions
버전 설정
macOS와 Windows 모두 동일한 명령어를 사용한다.
명령어 범위 설명
| pyenv global 3.12.0 |
시스템 전체 |
기본 Python 버전 지정 |
| pyenv local 3.10.0 |
현재 폴더 |
.python-version 파일 생성 |
| pyenv shell 3.9.0 |
현재 터미널 세션 |
세션 종료 시 초기화 |
local을 설정하면 해당 폴더에 진입할 때마다 자동으로 버전이 전환된다.
버전 확인
# 현재 사용 중인 버전 확인
pyenv version
# 설치된 모든 버전 확인 (* 표시가 현재 버전)
pyenv versions
버전 삭제
pyenv uninstall 3.10.0
자주 쓰는 명령어 요약
pyenv install --list # 설치 가능한 버전 목록
pyenv install 3.12.0 # 버전 설치
pyenv versions # 설치된 버전 목록
pyenv version # 현재 버전 확인
pyenv global 3.12.0 # 전역 버전 설정
pyenv local 3.10.0 # 로컬(프로젝트) 버전 설정
pyenv uninstall 3.10.0 # 버전 삭제
참고
- pyenv local로 설정된 .python-version 파일은 Git에 커밋해두면 팀원과 버전을 공유할 수 있다.
- Windows의 pyenv-win은 macOS/Linux용 pyenv와 별개 프로젝트로, 일부 기능에 차이가 있을 수 있다.