[Python] Part 2) pyenv 전환 후 버전 선택·python=python3 통합·free-threaded(…t) 빌드 가이드

 

Part 2) pyenv 전환 후 버전 선택·python=python3 통합·free-threaded(…t) 빌드 가이드

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

Apple Silicon Mac (M1~M4), zsh 기준

이 글은 Part 1(“Homebrew Python → pyenv 전환”)을 마친 뒤,
버전 선택(3.13.9 vs 3.13.9t), python과 python3의 일치, VSCode에서의 적용, 트러블슈팅을 한 번에 정리합니다.

---

TL;DR

• 주력 추천: 3.13.9(일반 빌드)
• 실험용: 3.13.9t = free-threaded(무 GIL) 빌드. 아직 많은 C 확장 패키지(NumPy/SciPy 등) 완전 호환X → “연구/벤치마크” 용도로만.
• python=python3 통일: pyenv의 shims가 자동으로 처리. 둘 다 ~/.pyenv/shims/...를 가리키면 OK.

---

1) 3.13.9와 3.13.9t, 무엇을 쓰나?

3.13.9 (일반 빌드)

• 최신 패치(보안/버그 포함), 생태계 호환성 우수.
• 실무·개발 기본 선택지로 강력 추천.

3.13.9t (free-threaded, 무 GIL)

• GIL을 약화/제거한 빌드. 멀티스레딩 성능 실험에 유리.
• C 확장 의존 라이브러리 호환 미완 → 서브/실험용으로만.

---

2) 둘 다 쓰고 싶다면(권장 운영 전략)

# 주력(일반 빌드)
pyenv install 3.13.9

# 실험용(무 GIL)
pyenv install 3.13.9t

# 전역 기본은 안정판으로
pyenv global 3.13.9
python -V
which python

# 특정 폴더에서만 free-threaded 써보기
mkdir -p ~/play/nogil-test && cd ~/play/nogil-test
pyenv local 3.13.9t
python -V   # 해당 폴더에서만 3.13.9t

프로젝트별 격리: 폴더마다 pyenv local <version>로 버전 고정
(예: 레거시 호환 폴더는 pyenv local 3.12.x)

---

3) python과 python3를 같은 버전으로 통일

pyenv는 shim으로 python과 python3를 자동 통일합니다. 아래처럼 둘 다 **~/.pyenv/shims/...**가 맨 위면 정상입니다.

which -a python python3
# 기대: ~/.pyenv/shims/python, ~/.pyenv/shims/python3 가 먼저

 

결과

 

맨 아래 /usr/bin/python3는 macOS 시스템에 기본 포함된 Python(Apple이 넣어둔 것)이고, 지우거나 건드릴 수 없습니다(SIP 보호). 중요한 건 PATH 우선순위인데, 지금 출력에서 보듯이

~/.pyenv/shims/python
~/.pyenv/shims/python3   ← 여기가 먼저
/usr/bin/python3         ← 시스템 Python (백업/최후 fallback)

 

셸이 먼저 pyenv shim을 찾습니다. 즉, 이미 pyenv가 우선 적용된 상태

점검 스니펫

python --version
python3 --version
python  -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.executable)"

• 둘 다 ~/.pyenv/versions/<ver>/bin/python(또는 python3)를 가리키면 OK.

만약 python3만 macOS 시스템(3.9.6)으로 새면

# 1) 셸 경로 캐시 비우기
hash -r         # zsh/bash 공통

# 2) pyenv shim 재생성
pyenv rehash

# 3) 혹시 예전에 alias 걸어둔 게 있으면 해제
unalias python3 2>/dev/null || true
unalias python   2>/dev/null || true

# 4) 이 세션만 강제로 3.13.9 우선 적용 (즉시 확인용)
pyenv shell 3.13.9

# 5) 경로/버전 확인
which -a python python3
python --version
python3 --version
python -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.executable)"

기대 결과
which -a가 둘 다 ~/.pyenv/shims/...를 맨 위로 보여야 합니다.
python3 --version이 Python 3.13.9로 바뀌고, python3의 executable도 ~/.pyenv/versions/3.13.9/bin/python3를 가리켜야 정상.

그래도 지속되면 초기화 라인이 로그인/비로그인 셸에 모두 있는지 확인:

grep -n 'PYENV_ROOT' ~/.zprofile ~/.zshrc 2>/dev/null
grep -n 'pyenv init'  ~/.zprofile ~/.zshrc 2>/dev/null

없으면 추가 후 exec $SHELL -l로 재시작.

---

4) VSCode에서 pyenv가 안 먹을 때

VSCode 내 터미널은 종종 비로그인 셸이라 ~/.zprofile이 적용 안 될 수 있습니다.
~/.zshrc에도 아래를 넣어주세요:

# ~/.zprofile에 이미 있다면 ~/.zshrc에도 추가
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
exec $SHELL -l

그리고 VSCode Python 인터프리터 선택 메뉴에서 원하는 pyenv 버전을 선택하세요(상단 Status Bar의 Python 버전 클릭).

---

5) 가상환경 권장 패턴

표준 venv

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

pyenv-virtualenv(선택)

brew install pyenv-virtualenv
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zprofile
exec $SHELL -l
pyenv virtualenv 3.13.9 std-3.13.9
pyenv virtualenv 3.13.9t nogil-3.13.9t
pyenv local std-3.13.9

---

6) 업데이트와 정리

# 최신 패치 확인
pyenv install -l | grep -E '^\s*3\.13\.[0-9]+$'

# 새 패치 설치 후 전환
pyenv install 3.13.10
pyenv global 3.13.10
pyenv rehash

# 필요 없어진 버전 삭제
pyenv uninstall 3.13.9

---

7) 빠른 체크리스트

• which -a python python3 → 둘 다 ~/.pyenv/shims/...가 첫 줄
• python --version = python3 --version
• python -m pip --version → ~/.pyenv/versions/<ver>/ 경로
• VSCode에서도 동일 버전 인식

---

결론

• 주력은 3.13.9(일반 빌드), free-threaded는 실험용으로 폴더 단위(pyenv local)로 격리.
• python과 python3는 pyenv shim이 자동 통일하므로 별도 alias 불필요.
• VSCode는 비로그인 셸 이슈만 유의하여 .zshrc에도 init을 추가하면 끝.