[개발환경] pyenv - Python 버전을 전환하면서 사용하기

macOS에서 Python 여러 버전 설치 및 전환하기 - pyenv

이전의 포스팅에서 Homebrew를 이용해서 파이썬 버전을 전환하면서 사용하는 방법을 알아보았습니다. 오늘은 실제 개발자들이 프로젝트별로 가상환경을 만들어서 프로젝트 별 파이썬 가상환경의 버전을 전환하면서 사용하는 'pyenv'를 알아보도록 하겠습니다.

 

Python을 사용하다 보면 특정 프로젝트는 최신 버전(예: 3.13)이 필요하고, 다른 프로젝트는 구버전(예: 3.9.13)을 요구하는 경우가 있습니다. 이런 상황에서는 여러 버전의 Python을 동시에 설치하고, 필요할 때마다 쉽게 전환할 수 있는 환경을 만드는 것이 중요합니다.

 

여기서는 pyenv라는 도구를 활용하는 방법을 소개합니다.

Python으로 개발할 때, 더 이상 버전으로 스트레스 받는일은 없을듯합니다.

[ 차례 ] 1. pyenv 설치 2. Python 3.9.13 설치 3. pyenv로 현재 사용 중인 버전 확인하는 방법 4. 여러 버전 전환하는 방법 5. 가상환경(venv)까지 함께 관리하기 6. Homebrew Python과 공존 7. Homebrew로 설치된 Python을 완전히 삭제하는 방법 7. 흔히 겪는 문제와 해결

pyenv를 활용한 다양한 버전의 python을 효율적으로 사용하기

---

1. pyenv 설치

먼저 pyenv를 설치해야 합니다. 이 도구는 여러 버전의 Python을 설치하고 관리할 수 있게 해줍니다.

brew update
brew install pyenv

# (선택) Python 빌드 시 필요한 라이브러리도 설치
brew install openssl readline zlib bzip2 sqlite xz

 

설치 후에는 터미널이 pyenv를 인식하도록 설정 파일에 초기화를 추가합니다. macOS에서 zsh를 쓰고 있다면:

# .zprofile: 로그인 시 실행되는 설정
echo 'eval "$(pyenv init -)"' >> ~/.zprofile

# .zshrc: 터미널 열릴 때마다 실행되는 설정
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 설정을 반영하기 위해 터미널 재시작
exec $SHELL -l

 

brew install pyenv로 pyenv를 설치한 뒤, 셸 초기화 코드(eval ...)를 .zprofile과 .zshrc에 추가해야 합니다.

.zshrc에 직접 추가하기

# pyenv 설정
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

---

2. Python 3.9.13 설치

이제 원하는 버전을 설치해봅시다. pyenv는 원하는 정확한 버전을 설치할 수 있습니다. homebrew를 이용해서 설치해도 가능하긴 합니다만 설치를 원하는 정확한 버전이 아닌 3.9.XX와 같이 homebrew에 빌드되어 있는 마이너버전이 다른 버전이 설치될 수 도 있습니다.

pyenv로 python 버전 골라서 설치하기

# pyenv로 설치가능한 버전 확인하기
pyenv install --list | grep " 3\."

# 설치버전 지정해서 설치하기
pyenv install 3.9.13

# 설치중 빌드에러가 발생하는 경우, 추가 패키지 설치
brew install openssl readline zlib bzip2 sqlite xz

# 설치된 버전 최종 확인
pyenv versions

  system
* 3.12.7 (set by /Users/denny/.pyenv/version)

실제 python 3.14.0을 설치하고 설치된 버전 확인하기

> pyenv install 3.14.0

python-build: use openssl@3 from homebrew
python-build: use readline from homebrew
Downloading Python-3.14.0.tar.xz...
-> https://www.python.org/ftp/python/3.14.0/Python-3.14.0.tar.xz
Installing Python-3.14.0...
python-build: use readline from homebrew
python-build: use ncurses from homebrew
python-build: use zlib from xcode sdk
Installed Python-3.14.0 to /Users/denny/.pyenv/versions/3.14.0

> pyenv versions                                                                                    ✔ │ 1m 27s │ system  │ 16:35:26 
* system (set by /Users/denny/.pyenv/version)
  3.14.0

pyenv로 python을 설치하는 경우 시간이 좀 걸릴 수 있습니다. pyenv는 소스 코드를 직접 빌드하기 때문이에요. 그 만큼 자신의 컴퓨터에 딱 맞는 python을 설치한다고 생각하면 오래 기다릴 수 있을겁니다.

---

3. pyenv로 현재 사용 중인 버전 확인하는 방법

• Homebrew로 설치된 Python은 기본적으로 pyenv “외부” 버전으로 인식되어 pyenv에서 자동으로 인식되지 않습니다.
• pyenv versions, pyenv version으로 현재 선택/활성화된 버전을 확인 가능하나, pyenv로 설치된 버전만 인식하게 됩니다.
• 우선순위는 shell > local > global > system의 우선순위를 갖습니다.

모든 설치된 버전 확인

pyenv versions

# 출력 예시
* system (set by /Users/username/.pyenv/version)
  3.9.13
  3.13.4

* 표시가 현재 선택된 버전입니다.

실제 실행되는 버전 확인

pyenv version

# 출력 예시
3.9.13 (set by /Users/username/myproject/.python-version)

어떤 경로의 Python을 쓰는지 확인

which python
which python3

---

4. 여러 버전 전환하는 방법

pyenv를 활성화하는 방법에는 세 가지 방식이 있습니다.

전체 기본 버전(global)

pyenv global 3.9.13

 

시스템 전체에서 기본 Python이 3.9.13으로 동작합니다. 다시 최신 버전을 쓰고 싶다면:

pyenv global 3.13.4

프로젝트 전용(local)

cd ~/myproject
pyenv local 3.9.13

해당 프로젝트 폴더 안에서는 무조건 3.9.13이 실행됩니다. 이 방식은 협업에도 유리합니다. .python-version 파일이 자동 생성되기 때문에, 다른 개발자도 동일 버전을 쓰게 만들 수 있습니다.

현재 터미널에서만(shell)

pyenv shell 3.9.13

이 명령은 현재 열려 있는 터미널 세션에서만 유효합니다. 터미널을 닫으면 원래 버전으로 돌아갑니다.

 

다이어그램 (pyenv 구조)

아래는 pyenv에서 global / local / shell이 어떻게 동작하는지 보여주는 간단한 다이어그램입니다:

               ┌───────────────────────────────┐
               │          pyenv                │
               │   (Python 버전 관리자)           │
               └───────────────────────────────┘
                                │
   ┌───────────────┬────────────┴────────────┬───────────────┐
   │               │                         │               │
Global          Local                     Shell           System
(전역 기본)     (프로젝트 전용)            (현재 터미널만)  (Homebrew 등 OS 기본)
   │               │                         │               │
   ▼               ▼                         ▼               ▼
 ~/.pyenv/      ./project/.python-version   터미널 세션    /usr/bin/python3
   (예:3.13)       (예:3.9.13)                (예:3.11)     /opt/homebrew/bin/python3

• shell > local > global > system 순서로 우선순위가 적용됩니다.
• 같은 환경에서도 어떤 버전을 쓰는지 pyenv가 “계층적으로” 결정해 줍니다.
• 예를 들어, 프로젝트 폴더 안에서 pyenv local 3.9.13을 지정하면 무조건 3.9.13을 씁니다.

---

5. 가상환경(venv)까지 함께 관리하기

프로젝트별로 독립적인 패키지 환경을 쓰려면 가상환경을 만드는 것이 좋습니다.

독립적인 가상환경 만들기

pyenv로 Python 버전을 선택한 뒤 :

pyenv shell 3.9.13
python -m venv .venv
source .venv/bin/activate
python -V

이렇게 하면 .venv라는 폴더에 가상환경이 만들어지고, 활성화하면 해당 환경에서만 패키지를 관리할 수 있습니다.
프로젝트마다 pyenv local + venv 조합으로 세팅하면 가장 깔끔합니다.

기존에 Homebrew로 설치된 python으로 만들어진 .venv가 있는경우 .venv를 삭제

# 활성화되어 있다면 먼저 비활성화
deactivate 2>/dev/null || true

# 잔해 확인
ls -la .venv 2>/dev/null || echo "no .venv"

# pyvenv.cfg가 남아 있으면 예전 경로(예: Homebrew)를 가리킵니다
[ -f .venv/pyvenv.cfg ] && cat .venv/pyvenv.cfg || true

# 깨끗이 제거
rm -rf .venv

동기화 폴더에서의 가상환경 다시 생성

SynologyDrive 같은 동기화 폴더에선 심볼릭 링크가 문제가 될 때가 많아서 --copies 옵션을 권장합니다. SynologyDriver와 같은 디스크 동기화 프로그램을 사용하는 경우 동기화 대상 컴퓨터간의 폴더 구조가 상이할 수 있어 설정된 가상환경이 자주 깨지는 경우가 발생할 수 있습니다. 

# pyenv의 정확한 인터프리터로 강제
"$(pyenv which python)" -m venv .venv --copies

# 활성화 & 기본 점검
source .venv/bin/activate
python --version
pip --version

.venv/pyvenv.cfg로 최종 점검

python의 가상환경이 만들어지는 경우 .venv/pyvenv.cfg에서 python과 관련된 설정값이 저장됩니다. 최종적으로 해당 파일을 점검해서 올바른 python을 지시하고 있는지 확인합니다.

home = /Users/user/.pyenv/versions/3.14.0/bin
include-system-site-packages = false
version = 3.14.0
executable = /Users/user/.pyenv/versions/3.14.0/bin/python3.14
command = /Users/user/.pyenv/versions/3.14.0/bin/python -m venv --copies /project folder/.venv

---

6. Homebrew Python과 공존

이미 Homebrew로 설치한 Python 3.13이 있어도 괜찮습니다. pyenv가 우선순위를 관리해 주기 때문에 충돌하지 않습니다.

• 최신 버전을 쓰려면 : pyenv shell 3.13.4
• 구버전을 쓰려면 : pyenv shell 3.9.13

절대경로(/opt/homebrew/Cellar/...)로 직접 실행할 수도 있지만, pyenv로 관리하는 것이 훨씬 편리합니다.

기존 Homebrew Python도 pyenv가 인식할까?

기본적으로 pyenv는 자기 폴더(~/.pyenv/versions)에 설치된 파이썬 버전만 관리합니다.
따라서 Homebrew로 설치한 Python (예: /opt/homebrew/Cellar/python@3.13/...)은 자동으로 pyenv가 인식하지 않습니다.

다만, 필요하다면 pyenv rehash나 pyenv prefix 등을 이용해서 연결하거나, 심볼릭 링크를 만들어서 외부 버전을 pyenv에 등록할 수는 있습니다. 하지만 일반적으로는 권장되지 않습니다. pyenv 안에서 설치하는 게 가장 안정적이에요.

 

Homebrew로 설치한 python과 pyenv로 설치한 파이썬을 정리해보면, 

• 지금 Homebrew로 설치된 3.13.x는 pyenv에서 “system”으로만 보입니다.
• 하지만 pyenv의 global/local/shell 전환 기능을 제대로 쓰려면, 3.13.x도 pyenv로 다시 설치하는 게 권장됩니다.

---

7. Homebrew로 설치된 Python을 완전히 삭제하는 방법

현재 Homebrew Python 설치 확인

 

brew list | grep python

# 일반적으로 다음과 같이 버전 목록을 표시합니다.
python@3.13
python@3.12

Homebrew로 설치된 python 모든 버전 제거

brew uninstall --ignore-dependencies python@3.13 
brew uninstall --ignore-dependencies python@3.12 
brew uninstall --ignore-dependencies python

# --ignore-dependencies 옵션은 다른 패키지가 Python을 참조하더라도 강제로 삭제합니다.

잔여 심볼릭 링크 / 캐시 제거

sudo rm -rf /usr/local/bin/python3 /usr/local/bin/pip3 
sudo rm -rf /opt/homebrew/bin/python3 /opt/homebrew/bin/pip3 
sudo rm -rf ~/Library/Caches/pip

삭제 확인

which python3 python3 --version

# 이 명령이 "command not found" 또는 "pyenv shims" 경로를 출력해야 정상입니다.
# 기존에 시스템에 설치되어 있는 python이 있는 경우 그래로 나두셔도 됩니다.

which python3                                                                                         ✔ │ 3s │ system  │ 16:19:56 
python3 --version

/Library/Frameworks/Python.framework/Versions/3.13/bin/python3
Python 3.13.1