[Python] Apple Silicon Mac에서 Homebrew Python → pyenv 전환 완벽 가이드

아래는 Apple Silicon Mac (M1~M4) 기준으로,
기존 Homebrew Python을 pyenv로 전환 + 버전 관리 + python=python3 통합까지 한 번에 완성하는 블로그용 가이드로 정리한 버전입니다.

---

🍎 Apple Silicon Mac에서 Homebrew Python → pyenv 전환 완벽 가이드

✅ 대상

• macOS on Apple Silicon (M1, M2, M3, M4)
• zsh 기준
• 기존에 Homebrew로 Python을 설치한 환경

---

1️⃣ 현재 환경 확인

python --version
which python
brew list --versions python python@3.13

출력이 이 형태라면 → Homebrew 버전이 맞습니다:

/usr/local/bin/python -> /opt/homebrew/bin/python3
python@3.13 3.13.3

---

2️⃣ Homebrew Python 언링크 (혹은 제거)

기존 파이썬이 PATH 앞쪽에 잡히는 걸 막습니다.

brew unlink python@3.13
# 완전 삭제하려면 문제 없는지 확인 후:
# brew uninstall --ignore-dependencies python@3.13

확인:

which -a python python3
# /opt/homebrew/bin/python3 가 더 이상 기본으로 안나와야 정상

---

3️⃣ pyenv 설치

brew install pyenv

빌드 의존성 (추천):

xcode-select --install       # Xcode Command Line Tools
brew install openssl readline zlib xz

---

4️⃣ zsh 초기화 설정 추가

~/.zprofile 또는 ~/.zshrc에 아래 내용을 추가합니다.
(파일이 없다면 자동 생성되어도 문제 없음)

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zprofile

비로그인 셸 (VSCode 내 터미널 등)에서도 동작하게 하려면 .zshrc에도 동일 추가:

echo 'eval "$(pyenv init -)"' >> ~/.zshrc

적용:

exec $SHELL -l
pyenv --version

---

5️⃣ 설치 가능한 Python 버전 목록 보기

pyenv install -l | grep -E '^\s*3\.(12|13)\.'

💡 참고: CPython에는 공식 LTS 표시는 없지만

• 안정/호환 우선 👉 3.12.x
• 최신 기능/성능 우선 👉 3.13.x
  를 일반적으로 권장합니다.

---

6️⃣ 원하는 버전 설치 및 전역 설정

예시 : 3.13.3 설치 후 전역 기본으로 적용

pyenv install 3.13.3
pyenv global 3.13.3

(필요하면 다른 버전도 추가 가능)

pyenv install 3.12.7

확인:

python --version
which -a python python3

결과:

Python 3.13.3
~/.pyenv/shims/python
~/.pyenv/shims/python3

👉 python과 python3가 자동으로 같은 pyenv shim을 가리킵니다.
따로 alias 필요 없습니다.

---

7️⃣ 프로젝트별 버전 고정 (선택)

특정 프로젝트에만 버전 고정하려면:

cd ~/projects/myapp
pyenv local 3.12.7

→ .python-version 파일이 생기며 그 디렉토리에서는 3.12.7이 적용됩니다.

---

8️⃣ 가상환경 (venv 또는 pyenv-virtualenv)

표준 venv:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

혹은 플러그인 방식:

brew install pyenv-virtualenv
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zprofile
exec $SHELL -l
pyenv virtualenv 3.13.3 myproj-3.13
pyenv local myproj-3.13

---

9️⃣ 업데이트 및 버전 전환

최신 버전 확인:

pyenv install -l | grep 3.13

새 패치 버전 설치:

pyenv install 3.13.4
pyenv global 3.13.4
pyenv rehash

삭제:

pyenv uninstall 3.13.3

---

🔟 트러블슈팅 포인트

증상 해결 방법

python이 여전히 /opt/homebrew/bin/python3 가리킴	brew unlink python@3.13 재확인 + exec $SHELL -l 재실행
pyenv 명령어 없음	.zprofile PATH 설정 누락 확인
빌드 에러	export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) 후 재시도
VSCode에서 pyenv 적용 안됨	VSCode 설정에서 "terminal.integrated.shellIntegration.enabled": true 확인 또는 .zshrc에도 동일 라인 추가

---

✅ 요약

항목 명령

Homebrew Python 비활성화	brew unlink python@3.13
pyenv 설치	brew install pyenv
셸 초기화	.zprofile 에 eval "$(pyenv init -)"
버전 설치	pyenv install 3.13.3
전역 적용	pyenv global 3.13.3
버전 확인	python --version, which python

---

🎯 결과

• ✅ python = python3 동일 경로 (shim)
• ✅ pyenv로 버전 스위칭 자유
• ✅ 시스템 Python 건드리지 않고 안정적인 환경 구성

---