💡 Mac에서 pyenv 버전 변경이 안 될 때 (python --version이 계속 3.9.6인 문제) 해결하기

# Mac에서 `pyenv` 버전 변경이 안 될 때 해결 방법 (`python --version`이 계속 3.9.6인 문제)

Mac에서 `pyenv`를 사용해 Python 버전을 관리하다 보면, 특정 디렉토리에서 `pyenv local 3.13.0` 명령을 실행했음에도 `python --version` 결과가 여전히 이전 버전(예: Python 3.9.6)으로 나오는 문제가 발생할 수 있습니다. 저도 `us-portfolio` 폴더에서 이 문제를 겪었는데, 이 글에서는 그 원인과 해결 방법을 단계별로 공유합니다.

```bash
➜  us-portfolio pyenv local 3.13.0
➜  us-portfolio python --version
Python 3.9.6

이 문제는 주로 셸 환경 설정과 관련된 PATH 순서 또는 별칭(Alias) 설정 때문에 발생합니다. 아래에서 문제를 진단하고 해결하는 과정을 자세히 설명합니다.

---

문제의 원인: PATH 순서와 별칭(Alias)

pyenv는 Python 버전을 관리하기 위해 심즈(shims)라는 메커니즘을 사용합니다. 이를 위해 $PATH 환경 변수에서 pyenv의 shims 디렉토리가 시스템 경로(/usr/bin, /usr/local/bin, /opt/homebrew/bin 등)보다 먼저 검색되어야 합니다.

하지만 터미널에서 $PATH를 확인했을 때, pyenv의 shims 경로가 누락되어 있거나 시스템 경로 뒤에 위치한 경우가 많습니다. 예를 들어:

➜  us-portfolio echo $PATH
/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/.../bin:/opt/homebrew/bin:...
# .pyenv/shims 경로가 없음!

또한, python3를 python으로 호출하기 위해 설정한 별칭(Alias)이 pyenv의 심즈 기능을 방해할 수 있습니다. 예를 들어, alias python=python3 같은 설정이 문제의 원인이 될 수 있습니다.

---

해결 방법

문제를 해결하려면 PATH 설정을 올바르게 구성하고, 불필요한 별칭을 제거해야 합니다. 아래는 단계별 해결 방법입니다.

1단계: 별칭(Alias) 제거

pyenv는 python 또는 python3 명령을 가로채서(shim) 지정한 Python 버전을 실행합니다. 하지만 셸 설정 파일에 alias python=python3 같은 별칭이 있으면 pyenv가 제대로 작동하지 않습니다.

1. 셸 설정 파일 열기
2. nano ~/.zshrc # 또는 vim ~/.zshrc
3. 별칭 제거

   # alias python=python3  # 주석 처리 또는 삭제

4. ~/.zshrc 파일에서 alias python=python3와 같은 줄을 찾아 삭제하거나, #을 붙여 주석 처리합니다.
5. 변경 사항 저장
6. 파일을 저장하고 닫습니다.

---

2단계: pyenv 초기화 설정 수정 및 PATH 최우선 지정

pyenv의 심즈 디렉토리가 $PATH의 가장 앞에 위치하도록 설정해야 합니다. 이를 위해 ~/.zshrc 파일에 pyenv 초기화 구문을 올바르게 추가합니다.

1. 셸 설정 파일 수정

   export PYENV_ROOT="$HOME/.pyenv"
   eval "$(pyenv init --path)"  # shims 경로를 PATH 최우선으로 추가
   eval "$(pyenv init -)"      # pyenv 셸 기능 활성화

주의: 이 구문이 다른 $PATH 설정보다 나중에 실행되도록 파일 끝부분에 추가하는 것이 중요합니다.

1.  
2. ~/.zshrc 파일을 다시 열고, 다음 구문을 파일의 맨 마지막 부분에 추가합니다. 이 구문은 pyenv의 shims 디렉토리를 $PATH의 최우선 순위로 설정합니다.
3. 설정 파일 재적용

   source ~/.zshrc

4. 수정된 설정을 현재 셸 세션에 적용합니다.

---

3단계: 최종 확인 🎉

설정을 적용한 후, pyenv가 제대로 작동하는지 확인합니다.

1. PATH 순서 확인

   echo $PATH
   # 결과 예시: .../.pyenv/shims:/usr/local/bin:...

   ~/.pyenv/shims가 맨 앞에 있으면 설정이 올바르게 적용된 것입니다.
2. shims 경로가 $PATH의 가장 앞에 위치하는지 확인합니다.
3. Python 버전 확인

   cd /path/to/us-portfolio
   python --version
   # 결과: Python 3.13.0  # 🎉 성공!

4. pyenv local을 설정했던 디렉토리로 이동해 Python 버전을 확인합니다.

---

핵심 요약

• pyenv가 올바르게 작동하려면 $PATH에서 $(pyenv root)/shims 경로가 시스템 경로(/usr/bin, /usr/local/bin, /opt/homebrew/bin 등)보다 먼저 검색되어야 합니다.
• python 또는 python3에 대한 별칭(Alias) 설정은 pyenv의 심즈 기능을 방해하므로 제거해야 합니다.
• ~/.zshrc에 pyenv 초기화 구문을 추가하고, source ~/.zshrc로 설정을 적용하세요.

---

마무리

위 단계를 따라 pyenv 버전 변경 문제를 해결하면, 원하는 Python 버전을 자유롭게 사용할 수 있습니다. 이 문제가 처음이라면 약간 복잡하게 느껴질 수 있지만, PATH와 별칭 설정을 이해하면 쉽게 해결할 수 있습니다. Python 개발 환경을 깔끔하게 관리하고 싶다면 pyenv는 정말 강력한 도구입니다!