파이썬 버전 관리: pyenv

이번 편에서는 본격적으로 개발 환경을 세팅합니다.

가장 먼저 부딪히는 문제가 "파이썬 버전을 어떻게 관리할 것인가"인데, 이걸 제대로 이해하지 않고 넘어가면 나중에 패키지 의존성 충돌 같은 문제를 맞닥뜨렸을 때 원인 파악이 한참 걸립니다.

---

시스템에 기본 설치된 파이썬을 그대로 쓰면 안 되는 이유

처음엔 "그냥 컴퓨터에 깔려있는 파이썬 쓰면 되는 거 아닌가" 싶은데, 찾아보면 생각보다 문제가 많습니다.

• sudo pip install로 패키지를 깔면 시스템 전체에 영향을 주는데, 프로젝트마다 원하는 패키지 버전이 다를 수 있습니다. 같은 패키지라도 버전이 섞이면 예상치 못한 오류가 발생하기 쉽습니다.
• OS에 기본 설치된 파이썬 버전이 너무 오래된 경우도 많습니다.
• 일부 운영체제는 내부적으로 시스템 동작에 파이썬을 사용하기 때문에(예: yum 같은 패키지 관리자), 이 시스템 파이썬을 잘못 건드리면 OS 자체가 망가질 수도 있습니다.

예를 들어 프로젝트 A, B, C가 각각 다른 pandas/pytorch 버전을 요구한다고 가정해보면, 시스템 파이썬 하나에 모든 패키지를 다 깔아서 쓰는 방식으로는 답이 없습니다.

결국 프로젝트별로 독립된 파이썬 환경이 필요하다는 결론에 도달하게 됩니다.

---

가상환경 관리와 패키지 관리는 별개의 문제

여기서 헷갈리기 쉬운 부분이 하나 있는데, 파이썬 생태계에서는 "어떤 파이썬 버전을 쓸 것인가(가상환경 관리)"와 "그 환경에 어떤 패키지를 설치할 것인가(패키지 관리)"가 서로 다른 영역이라는 점입니다.

• 가상환경 관리 도구: conda, venv, virtualenv, pyenv 등
• 패키지 관리 도구: conda, pip, pipenv, poetry, pdm 등

conda처럼 두 역할을 동시에 하는 도구도 있지만, 이번 학습에서는 가상환경 관리는 pyenv, 패키지 관리는 다음 편에서 다룰 poetry로 역할을 나눠서 사용하는 방식을 정리합니다.

---

pyenv란

pyenv는 한 컴퓨터 안에서 여러 버전의 파이썬을 설치하고 자유롭게 전환할 수 있게 해주는 도구입니다.

핵심은 시스템 파이썬을 건드리지 않고도 프로젝트마다 독립적인 파이썬 버전을 지정할 수 있다는 점입니다.

버전 우선순위 개념

pyenv가 어떤 파이썬 버전을 쓸지 결정하는 기준에는 우선순위가 있습니다.

이 부분이 사실 pyenv를 이해하는 데 가장 중요한 개념이라고 느꼈습니다.

1. Shell — 현재 셸 세션에만 일시적으로 적용된 버전
2. Local — 특정 디렉토리에 지정된 버전 (.python-version 파일)
3. Global — 시스템 전역 기본값
4. System — pyenv를 설치하기 전부터 있던 원래 시스템 파이썬

우선순위는 shell > local > global > system 순서입니다.

즉 가장 좁은 범위(현재 세션)에 설정된 값이 가장 넓은 범위(시스템 전체)의 값보다 항상 우선합니다.

이 구조 덕분에 프로젝트 A는 3.8, 프로젝트 B는 3.11처럼 디렉토리별로 다른 버전을 자연스럽게 쓸 수 있게 됩니다.

설치 및 기본 사용법

설치는 공식 설치 스크립트로 진행합니다.

curl <https://pyenv.run> | bash

 

설치 후에는 ~/.bashrc에 초기화 구문을 추가해야 셸이 시작될 때마다 pyenv가 정상적으로 동작합니다.

# >>> pyenv >>>
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# <<< pyenv <<<

 

설정을 반영한 뒤 버전 확인으로 설치를 검증합니다.

source ~/.bashrc
pyenv --version

파이썬 버전 설치하기

pyenv install --list   # 설치 가능한 버전 목록 확인
pyenv install 3.11     # 원하는 버전 설치

global / local / shell 적용

여기서부터는 직접 손으로 따라 해봐야 감이 잡히는 부분입니다.

pyenv versions          # 현재 pyenv가 관리 중인 버전 목록
pyenv global 3.12       # 전역 기본 버전 설정
python -V               # 적용된 버전 확인

 

특정 디렉토리에서만 다른 버전을 쓰고 싶다면 local을 사용합니다.

이렇게 하면 해당 디렉토리에 .python-version 파일이 생기고, 그 디렉토리 안에서는 이 버전이 global보다 우선 적용됩니다.

pyenv local 3.11
cat .python-version      # 어떤 버전이 지정됐는지 확인

 

shell은 더 임시적인 단위로, 현재 터미널 세션에서만 일시적으로 버전을 바꾸고 싶을 때 씁니다.

세션을 닫거나 --unset으로 해제하면 다시 local/global 우선순위로 돌아갑니다.

pyenv shell 3.10
echo $PYENV_VERSION       # 일시적으로 적용된 버전 확인
pyenv shell --unset       # 해제

직접 해보면서 느낀 점은, pyenv가 버전을 결정하는 방식이 "환경변수 우선 → 디렉토리 설정 → 전역 설정 → 시스템 기본값" 순서로 차곡차곡 내려간다는 걸 이해하고 나면 헷갈릴 일이 거의 없다는 것입니다.

파이썬 가상환경(virtualenv) 만들기

pyenv는 단순히 버전 전환뿐 아니라 pyenv-virtualenv 플러그인을 통해 가상환경 자체도 만들고 관리할 수 있습니다.

pyenv virtualenv 3.12 py312   # 3.12 버전 기반 가상환경 생성
pyenv activate py312           # 활성화
pyenv deactivate                # 비활성화
pyenv uninstall py312           # 가상환경 삭제

pyenv 삭제

설치 위치를 확인한 뒤 해당 디렉토리를 통째로 지우면 됩니다.

pyenv root        # 설치 위치 확인
rm -rf ~/.pyenv    # 디렉토리 삭제