Python pyenv 설치 방법과 사용법 (완벽 가이드)

1. pyenv란 무엇인가?

pyenv는 다양한 버전의 Python을 손쉽게 설치하고 관리할 수 있는 도구입니다. 보통 시스템에 기본적으로 설치된 Python을 사용하면 여러 프로젝트에서 버전 충돌이 발생할 수 있습니다. 이를 해결하기 위해 pyenv를 사용하면 프로젝트별로 Python 버전을 다르게 설정할 수 있습니다.

** Node의 nvm과 같은 기능으로 보면 된다. 

pyenv의 주요 기능

• 여러 버전의 Python을 동시에 관리 가능
• 프로젝트별로 다른 Python 버전을 적용 가능
• Python 가상환경을 생성하는 pyenv-virtualenv 플러그인 지원

---

2. pyenv 설치 방법

1) macOS에서 설치

Homebrew를 사용하여 설치

brew update
brew install pyenv

설치 후, pyenv가 정상적으로 설치되었는지 확인:

pyenv -v

2) Ubuntu 및 Debian 계열에서 설치

필요한 패키지 설치

sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncurses5-dev libncursesw5-dev xz-utils tk-dev \
  libffi-dev liblzma-dev python-openssl git

pyenv 설치

curl https://pyenv.run | bash

3) Windows에서 설치

Windows에서는 pyenv 대신 pyenv-win을 사용해야 합니다.

git clone https://github.com/pyenv-win/pyenv-win.git $HOME/.pyenv

환경 변수 설정:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

이후 정상적으로 설치되었는지 확인:

pyenv --version

---

3. pyenv 설정 (공통 과정)

설치 후, pyenv를 사용하려면 셸 환경 변수를 설정해야 합니다.

1) Bash 또는 Zsh 환경 설정

다음 명령을 ~/.bashrc 또는 ~/.zshrc 파일에 추가합니다.

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

설정 적용:

source ~/.bashrc  # Bash 사용 시
source ~/.zshrc   # Zsh 사용 시

2) pyenv-doctor로 설치 확인

제대로 설치되었는지 확인하려면 pyenv-doctor 플러그인을 설치하고 실행합니다.

git clone https://github.com/pyenv/pyenv-doctor.git "$(pyenv root)/plugins/pyenv-doctor"
pyenv doctor

---

4. Python 버전 설치 및 관리

설치가 완료되면 pyenv를 사용하여 Python 버전을 설치하고 관리할 수 있습니다.

1) 설치 가능한 Python 버전 목록 확인

pyenv install --list

출력 예시:

3.7.12
3.8.12
3.9.9
3.10.2
3.11.1

2) 특정 Python 버전 설치

예를 들어 Python 3.10.2를 설치하려면:

pyenv install 3.10.2

3) 설치된 Python 버전 확인

pyenv versions

출력 예시:

  system
  3.9.9
* 3.10.2 (set by /home/user/.pyenv/version)

4) 기본 사용 Python 버전 설정

시스템 전체에서 특정 Python 버전을 기본값으로 설정하려면:

pyenv global 3.10.2

개별 프로젝트 폴더에서만 적용하려면:

pyenv local 3.10.2

현재 터미널 세션에서만 적용하려면:

pyenv shell 3.10.2

---

5. pyenv-virtualenv로 가상환경 관리

pyenv에는 가상환경을 지원하는 pyenv-virtualenv 플러그인이 있습니다.

1) pyenv-virtualenv 설치

git clone https://github.com/pyenv/pyenv-virtualenv.git "$(pyenv root)/plugins/pyenv-virtualenv"

환경 변수 추가:

echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc

2) 가상환경 생성

예를 들어 myenv라는 가상환경을 만들고 싶다면:

pyenv virtualenv 3.10.2 myenv

3) 가상환경 활성화 및 비활성화

가상환경 활성화:

pyenv activate myenv

가상환경 비활성화:

pyenv deactivate

4) 특정 프로젝트에 가상환경 자동 적용

특정 디렉터리에서 가상환경을 자동으로 활성화하려면:

pyenv local myenv

이렇게 설정하면 해당 디렉터리에 들어갈 때마다 myenv가 자동으로 활성화됩니다.

---

6. pyenv 문제 해결

1) pyenv 실행이 안 될 때

pyenv 명령어가 실행되지 않는다면 환경 변수를 다시 확인하고 적용하세요.

echo $PATH

$PYENV_ROOT/bin 경로가 없다면 직접 추가해야 합니다.

2) Python 빌드 오류 발생 시

Python 빌드 중 make 관련 오류가 발생한다면, 필요한 패키지가 누락되었을 가능성이 있습니다. 다음 명령어로 필수 패키지를 다시 설치하세요.

sudo apt install -y make build-essential

3) pyenv-virtualenv가 작동하지 않을 때

설치 후 pyenv virtualenv-init을 환경 변수에 추가했는지 확인하세요.

eval "$(pyenv virtualenv-init -)"

또는 .bashrc나 .zshrc에 추가했는지 확인하세요.

---

7. 정리 및 결론

pyenv를 사용하면 Python 버전을 프로젝트별로 다르게 설정할 수 있고, 가상환경을 활용하여 독립적인 환경을 유지할 수 있습니다. 특히 pyenv-virtualenv를 함께 사용하면 venv보다 더 편리한 가상환경 관리가 가능합니다.

핵심 요약

1. pyenv를 사용하면 여러 Python 버전을 쉽게 설치하고 전환할 수 있음.
2. pyenv install <version>으로 원하는 버전의 Python 설치 가능.
3. pyenv global <version> 또는 pyenv local <version>으로 적용 가능.
4. pyenv-virtualenv를 사용하면 프로젝트별 가상환경 관리 가능.
5. 환경 변수를 올바르게 설정해야 정상 동작함.

이제 pyenv를 활용하여 Python 개발 환경을 효과적으로 관리해보세요! 🚀

---