[Python] pyenv: 다양한 Python 버전을 간편하게 관리하는 방법

Python 개발에서 종종 겪는 문제 중 하나는 프로젝트마다 요구되는 Python 버전이 다를 때 발생한다. 이럴 때 사용하는 도구가 바로 pyenv이다. 이번 포스트에서는 pyenv의 개념, 주요 기능, 설치 및 사용법, 그리고 실전 활용 사례를 상세히 다뤄 보고자 한다.

Table of Contents　

pyenv란 무엇인가?

pyenv는 여러 버전의 Python을 설치하고 관리할 수 있는 도구다. 특정 프로젝트에서 요구하는 Python 버전을 손쉽게 설정하거나 전환할 수 있도록 도와준다.

주요 기능

다양한 Python 버전 설치: 최신 버전부터 오래된 버전, 심지어 특정 빌드의 버전까지 지원.
버전 전환: 전역, 디렉토리(프로젝트), 쉘 세션 단위로 Python 버전을 전환 가능.
가상 환경과 연동: venv나 virtualenv와 함께 사용해 Python 환경 관리 가능.
간편한 설치 및 제거: 명령어 몇 줄로 Python 버전 추가/삭제 가능.

pyenv 설치

macOS/Linux 설치

설치 명령 실행

curl https://pyenv.run | bash

환경 설정: 설치 후 ~/.bashrc, ~/.zshrc, ~/.bash_profile 등의 쉘 설정 파일에 아래 코드를 추가한다

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

쉘 재시작: 쉘 설정 파일을 적용한다

source ~/.bashrc

설치 확인

pyenv --version

Windows 설치

Windows에서는 pyenv-win을 사용한다.

pyenv-win 설치

pip install pyenv-win

환경 변수 설정: Windows 시스템 설정에서 PYENV와 관련된 환경 변수를 추가한다

PYENV: 설치된 pyenv 디렉토리 경로
(C:\Users\<사용자>\.pyenv\pyenv-win) or,
(C:\Users\<사용자>\anaconda3\Lib\site-packages\pyenv-win)
PATH: PYENV\bin 및 PYENV\shims 디렉토리를 추가.

설치 확인

pyenv --version

pyenv 사용법

Python 버전 검색 및 설치

사용 가능한 Python 버전 검색: 최신 버전, LTS 버전, 과거 버전 등 다양한 선택지가 제공된다.

pyenv install --list

Python 버전 설치

pyenv install <버전>

pyenv install 3.10.5
pyenv install 3.9.8

설치된 버전 확인

pyenv versions

Python 버전 전환

전역(Global) 설정: 기본적으로 사용하는 Python 버전을 설정한다

pyenv global <버전>

pyenv global 3.10.5

디렉토리(Local) 설정: 특정 디렉토리(프로젝트)에서만 사용하는 Python 버전을 설정한다

pyenv local <버전>

pyenv local 3.8.5

쉘(Shell) 설정: 현재 터미널 세션에서만 사용할 Python 버전을 설정한다

pyenv shell <버전>

현재 활성화된 Python 버전 확인

pyenv version

Python 버전 삭제

더 이상 필요 없는 Python 버전을 제거한다.

pyenv uninstall <버전>

pyenv uninstall 3.9.7

pyenv 활용 사례

프로젝트별 Python 버전 관리

프로젝트마다 다른 Python 버전이 필요한 경우, pyenv local을 활용한다.

프로젝트 A: Python 3.10.5
프로젝트 B: Python 3.8.2

# 프로젝트 A 디렉토리
cd project_a
pyenv local 3.10.5

# 프로젝트 B 디렉토리
cd project_b
pyenv local 3.8.2

해당 디렉토리로 이동하면 자동으로 지정된 Python 버전이 활성화된다.

문제 해결

문제 1: 설치된 Python 버전이 인식되지 않을 때

해결 방법: pyenv rehash 명령어 실행.

문제 2: Windows에서 실행 오류

해결 방법:

PATH 환경 변수가 올바르게 설정되었는지 확인.
PowerShell 실행 정책을 Unrestricted로 변경

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine

문제 3: 특정 버전 설치 실패