pyenv 파이썬 버전 관리 완벽 가이드

여러 파이썬 프로젝트를 진행하다 보면 버전 충돌 문제에 직면하게 됩니다. 레거시 프로젝트는 Python 2.7, 새 프로젝트는 3.12를 요구하는 상황에서 어떻게 해야 할까요? 이 글에서는 pyenv와 pyenv-virtualenv를 활용한 완벽한 파이썬 버전 관리 방법을 알려드립니다.

pyenv가 필요한 이유

파이썬 라이브러리와 프레임워크는 각각 다른 파이썬 버전을 요구합니다. Django 4.2는 Python 3.8 이상, TensorFlow 2.15는 3.9-3.11만 지원하는 식입니다. 시스템 파이썬만 사용하면 프로젝트마다 버전을 바꿀 수 없고, 패키지 충돌도 발생합니다. pyenv는 여러 파이썬 버전을 설치하고 프로젝트별로 다른 버전을 사용할 수 있게 해줍니다.

pyenv vs virtualenv 차이점

pyenv: 파이썬 버전 관리 (2.7, 3.8, 3.12 등을 동시에 설치)

virtualenv: 패키지 격리 (같은 파이썬 버전에서 프로젝트별 패키지 분리)

pyenv-virtualenv: pyenv + virtualenv 조합 (버전 + 패키지 모두 격리)

macOS 설치 방법

1단계: Homebrew로 pyenv 설치

# Homebrew 업데이트
brew update && brew upgrade

# pyenv 설치
brew install pyenv

# pyenv-virtualenv 설치
brew install pyenv-virtualenv

# 설치 확인
pyenv --version
# pyenv 2.3.36

2단계: 필수 의존성 설치

# Xcode Command Line Tools
sudo xcode-select --install

# 빌드 도구
brew install openssl readline sqlite3 xz zlib

# Python 컴파일에 필요한 라이브러리
brew install tcl-tk

중요: 이 패키지들이 없으면 파이썬 설치 중 오류가 발생합니다.

3단계: 환경변수 설정

Bash 사용자:

# ~/.bash_profile 또는 ~/.bashrc 파일 편집
nano ~/.bash_profile

# 아래 내용 추가
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# 적용
source ~/.bash_profile

Zsh 사용자 (macOS 기본):

# ~/.zshrc 파일 편집
nano ~/.zshrc

# 아래 내용 추가
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# 적용
source ~/.zshrc

설정 확인:

# 터미널을 재시작하거나 source 명령 후
which pyenv
# /Users/username/.pyenv/bin/pyenv

echo $PYENV_ROOT
# /Users/username/.pyenv

Linux (Ubuntu/CentOS) 설치

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 \\\\
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \\\\
  libffi-dev liblzma-dev

# pyenv 설치
curl <https://pyenv.run> | bash

# 환경변수 설정 (~/.bashrc에 추가)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc

# 적용
source ~/.bashrc

CentOS/RHEL

# 필수 패키지
sudo yum groupinstall -y "Development Tools"
sudo yum install -y gcc zlib-devel bzip2 bzip2-devel readline-devel \\\\
  sqlite sqlite-devel openssl-devel xz xz-devel libffi-devel

# pyenv 설치
curl <https://pyenv.run> | bash

# 환경변수 설정 (~/.bashrc에 추가)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc

# 적용
source ~/.bashrc

파이썬 버전 설치

설치 가능한 버전 확인

# 모든 설치 가능한 버전 보기
pyenv install --list

# 최신 3.x 버전만 보기
pyenv install --list | grep "^\\\\s*3\\\\."

# 특정 버전 검색
pyenv install --list | grep 3.12

파이썬 설치

# Python 3.12 최신 버전 설치
pyenv install 3.12.0

# Python 3.11 설치
pyenv install 3.11.7

# Python 3.9 설치 (레거시 프로젝트용)
pyenv install 3.9.18

# Python 2.7 설치 (아주 오래된 프로젝트)
pyenv install 2.7.18

# 설치 진행 상황 확인
# 컴파일 중... (5-15분 소요)

설치 시간: 버전과 시스템 성능에 따라 5-15분 소요

설치된 버전 확인

# 설치된 모든 버전 보기
pyenv versions

# 출력 예시:
# * system (set by /Users/username/.pyenv/version)
#   3.9.18
#   3.11.7
#   3.12.0

# * 표시는 현재 활성화된 버전

파이썬 버전 전환

전역(Global) 버전 설정

# 시스템 전체에서 사용할 기본 버전
pyenv global 3.12.0

# 확인
python --version
# Python 3.12.0

pyenv versions
# * 3.12.0 (set by /Users/username/.pyenv/version)
#   3.11.7
#   3.9.18

적용 범위: 모든 디렉토리에서 기본적으로 사용

로컬(Local) 버전 설정

# 프로젝트 디렉토리로 이동
mkdir ~/project-legacy
cd ~/project-legacy

# 이 디렉토리에서만 Python 3.9 사용
pyenv local 3.9.18

# 확인
python --version
# Python 3.9.18

# .python-version 파일 생성됨
cat .python-version
# 3.9.18

# 다른 디렉토리로 이동하면 global 버전 사용
cd ~
python --version
# Python 3.12.0

적용 범위: 해당 디렉토리와 하위 디렉토리에서만 적용

쉘(Shell) 버전 설정

# 현재 쉘 세션에서만 임시로 변경
pyenv shell 3.11.7

# 확인
python --version
# Python 3.11.7

# 해제
pyenv shell --unset

# 또는 터미널 재시작하면 자동 해제

적용 범위: 현재 터미널 세션에서만 적용

가상환경 생성 및 관리

가상환경 생성

# 기본 형식: pyenv virtualenv <python-version> <env-name>

# Python 3.12로 django-project 가상환경 생성
pyenv virtualenv 3.12.0 django-project

# Python 3.9로 flask-app 가상환경 생성
pyenv virtualenv 3.9.18 flask-app

# 버전 생략 시 현재 global 버전 사용
pyenv virtualenv my-project

# 생성된 가상환경 확인
pyenv versions
# * 3.12.0 (set by ...)
#   3.11.7
#   3.9.18
#   3.12.0/envs/django-project
#   django-project
#   3.9.18/envs/flask-app
#   flask-app

가상환경 활성화

# 수동 활성화
pyenv activate django-project

# 프롬프트 변경됨
# (django-project) username@macbook:~$

# 확인
python --version
# Python 3.12.0

which python
# /Users/username/.pyenv/versions/django-project/bin/python

# 비활성화
pyenv deactivate

프로젝트에 가상환경 자동 적용

# 프로젝트 디렉토리 생성
mkdir ~/django-project
cd ~/django-project

# 가상환경을 local로 설정
pyenv local django-project

# 이제 이 디렉토리에 들어오면 자동 활성화됨
cd ~/django-project
# (django-project) username@macbook:~/django-project$

# 다른 곳으로 이동하면 자동 비활성화
cd ~
# username@macbook:~$

자동 활성화: pyenv virtualenv-init가 설정되어 있으면 자동으로 작동

가상환경 삭제

# 가상환경 삭제
pyenv uninstall django-project

# 확인 메시지
# pyenv: remove /Users/username/.pyenv/versions/3.12.0/envs/django-project? [y|N] y

# 파이썬 버전도 삭제 가능
pyenv uninstall 3.9.18

실전 프로젝트 설정 예제

예제 1: Django 프로젝트

# 1. 프로젝트 디렉토리 생성
mkdir ~/my-django-blog
cd ~/my-django-blog

# 2. Python 3.12 설치 (없다면)
pyenv install 3.12.0

# 3. 가상환경 생성
pyenv virtualenv 3.12.0 django-blog-env

# 4. 가상환경 적용
pyenv local django-blog-env

# 5. Django 설치
pip install --upgrade pip
pip install django

# 6. Django 프로젝트 시작
django-admin startproject mysite .

# 7. requirements.txt 생성
pip freeze > requirements.txt

# 8. Git 설정
echo ".python-version" >> .gitignore

# 9. 확인
python --version
# Python 3.12.0

pip list
# Django 5.0
# ...

예제 2: Flask API 프로젝트

# 1. 프로젝트 설정
mkdir ~/flask-api
cd ~/flask-api

# 2. Python 3.11로 가상환경
pyenv virtualenv 3.11.7 flask-api-env
pyenv local flask-api-env

# 3. Flask 설치
pip install flask flask-cors python-dotenv

# 4. 프로젝트 파일 생성
cat > app.py << 'EOF'
from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return {'message': 'Hello from Flask!'}

if __name__ == '__main__':
    app.run(debug=True)
EOF

# 5. 실행
python app.py

# 6. requirements.txt
pip freeze > requirements.txt

예제 3: 데이터 분석 프로젝트

# 1. 프로젝트 설정
mkdir ~/data-analysis
cd ~/data-analysis

# 2. Python 3.10 (안정성)
pyenv install 3.10.13
pyenv virtualenv 3.10.13 data-env
pyenv local data-env

# 3. 데이터 분석 라이브러리 설치
pip install numpy pandas matplotlib seaborn jupyter scikit-learn

# 4. Jupyter 실행
jupyter notebook

# 5. requirements 저장
pip freeze > requirements.txt

예제 4: 레거시 프로젝트 (Python 2.7)

# 1. 옛날 프로젝트
mkdir ~/legacy-project
cd ~/legacy-project

# 2. Python 2.7 설치
pyenv install 2.7.18

# 3. 가상환경
pyenv virtualenv 2.7.18 legacy-env
pyenv local legacy-env

# 4. 의존성 설치
pip install -r requirements.txt

# 5. 실행
python old_script.py

패키지 관리

requirements.txt 활용

# 현재 환경의 패키지 저장
pip freeze > requirements.txt

# 내용 확인
cat requirements.txt
# Django==5.0.1
# requests==2.31.0
# pandas==2.1.4

# 다른 환경에서 설치
pip install -r requirements.txt

# 특정 패키지만 업데이트
pip install --upgrade django

# 업데이트 후 다시 저장
pip freeze > requirements.txt

개발 환경과 프로덕션 분리

# 개발 환경
pip freeze > requirements-dev.txt

# 프로덕션 환경 (테스트 패키지 제외)
pip freeze | grep -v "pytest\\\\|black\\\\|flake8" > requirements.txt

# 또는 수동으로 분리
cat > requirements.txt << 'EOF'
Django==5.0.1
psycopg2-binary==2.9.9
gunicorn==21.2.0
EOF

cat > requirements-dev.txt << 'EOF'
-r requirements.txt
pytest==7.4.3
black==23.12.1
flake8==7.0.0
EOF

# 설치
pip install -r requirements-dev.txt

자주 사용하는 명령어 정리

# 설치 관련
pyenv install --list                    # 설치 가능한 버전 목록
pyenv install 3.12.0                    # 파이썬 설치
pyenv uninstall 3.9.18                  # 파이썬 삭제

# 버전 확인 및 전환
pyenv versions                          # 설치된 버전 확인
pyenv version                           # 현재 활성 버전
pyenv global 3.12.0                     # 전역 버전 설정
pyenv local 3.11.7                      # 로컬 버전 설정
pyenv shell 3.9.18                      # 쉘 버전 설정

# 가상환경
pyenv virtualenv 3.12.0 myenv           # 가상환경 생성
pyenv activate myenv                    # 활성화
pyenv deactivate                        # 비활성화
pyenv virtualenvs                       # 가상환경 목록
pyenv uninstall myenv                   # 가상환경 삭제

# 기타
pyenv which python                      # python 실행파일 위치
pyenv which pip                         # pip 실행파일 위치
pyenv rehash                            # shim 재생성 (수동, 보통 자동)

문제 해결

문제 1: pyenv 명령어를 찾을 수 없음

# 환경변수 확인
echo $PATH | grep pyenv

# 없으면 ~/.bashrc 또는 ~/.zshrc에 추가
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

# 적용
source ~/.zshrc  # 또는 ~/.bashrc

문제 2: Python 설치 실패

# 로그 확인
cat /tmp/python-build.*.log

# macOS: Xcode Command Line Tools 재설치
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

# 빌드 도구 재설치
brew reinstall openssl readline sqlite3 xz zlib

# 환경변수 설정 후 재시도
export LDFLAGS="-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include -I$(brew --prefix readline)/include"

pyenv install 3.12.0

문제 3: pip 명령어 오류

# pip 업그레이드
python -m pip install --upgrade pip

# pip 재설치
curl <https://bootstrap.pypa.io/get-pip.py> -o get-pip.py
python get-pip.py

# pyenv rehash
pyenv rehash

문제 4: 가상환경이 자동 활성화되지 않음

# virtualenv-init 확인
cat ~/.zshrc | grep virtualenv

# 없으면 추가
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
source ~/.zshrc

문제 5: Homebrew shallow clone 오류

# macOS Homebrew 오류 해결
git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core fetch --unshallow
git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask fetch --unshallow

# 업데이트
brew update && brew upgrade

팀 협업 설정

.python-version 파일 공유

# 프로젝트 루트에 .python-version 생성
echo "3.12.0" > .python-version

# Git에 커밋
git add .python-version
git commit -m "Add Python version specification"

# 팀원이 clone 후
cd project
pyenv install  # .python-version 읽고 자동 설치

README.md에 설정 가이드 추가

# 프로젝트명

## 개발 환경 설정

### 1. pyenv 설치
\\\\```bash
# macOS
brew install pyenv pyenv-virtualenv

# Linux
curl <https://pyenv.run> | bash
\\\\```

### 2. 파이썬 및 가상환경 설정
\\\\```bash
# 파이썬 설치
pyenv install

# 가상환경 생성 및 활성화
pyenv virtualenv $(cat .python-version) myproject-env
pyenv local myproject-env

# 의존성 설치
pip install -r requirements.txt
\\\\```

### 3. 실행
\\\\```bash
python manage.py runserver
\\\\```

마치며

pyenv는 pyenv install로 여러 파이썬 버전을 설치하고, pyenv global/local로 버전을 전환하며, pyenv virtualenv로 가상환경을 생성하는 3단계로 완벽한 파이썬 버전 관리가 가능합니다.

프로젝트마다 .python-version 파일로 버전을 명시하고, requirements.txt로 의존성을 관리하면 팀 협업도 원활해집니다. 레거시 프로젝트부터 최신 프로젝트까지 버전 충돌 없이 동시에 개발할 수 있습니다.

이 가이드를 활용해 깔끔한 파이썬 개발 환경을 구축하세요!

---

참고 자료

• pyenv GitHub: https://github.com/pyenv/pyenv
• pyenv-virtualenv GitHub: https://github.com/pyenv/pyenv-virtualenv
• Python 공식 다운로드: https://www.python.org/downloads/