안녕하세요 👋
이번 글에서는 MacOS에서 pyenv를 이용해 Python 버전을 관리하고,
그 위에 가상환경(venv) 를 구성하는 실무형 개발환경 세팅 방법을 정리해보겠습니다.
🎯 왜 pyenv를 써야 할까?
MacOS에는 기본적으로 Python이 내장되어 있지만,
이건 시스템용이라 함부로 건드리면 macOS 자체 기능이 깨질 수 있습니다.
✅ 그래서 “시스템 Python”과 “개발용 Python”을 분리해야 합니다.
pyenv는 여러 Python 버전을 동시에 설치하고 전환할 수 있게 해주는 도구입니다.
즉, 프로젝트마다 다른 Python 버전을 안전하게 사용할 수 있습니다.
⚙️ 1. pyenv 설치
🍺 Homebrew를 이용해 설치
brew update
brew install pyenv설치가 끝나면 다음 경로를 쉘 설정에 등록해야 합니다.
사용 중인 쉘에 따라 아래 중 하나를 선택하세요.
Zsh 사용 시 (.zshrc)
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zprofile
source ~/.zshrcBash 사용 시 (.bash_profile)
echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bash_profile🧱 2. Python 버전 설치
설치 가능한 버전 목록을 먼저 확인해 봅니다.
pyenv install --list예를 들어 Python 3.12.3 버전을 설치하려면:
pyenv install 3.12.3설치 후 확인:
pyenv versions결과 예시:
* system
3.12.3 (set by /Users/seungho/.pyenv/version)🔄 3. 전역(Global) 또는 로컬(Local) 버전 설정
전역 버전 설정 (모든 폴더에 기본 적용)
pyenv global 3.12.3특정 프로젝트에만 적용
cd ~/projects/myapp
pyenv local 3.12.3이 명령을 실행하면 해당 폴더에 .python-version 파일이 생성됩니다.
이제 해당 디렉터리에서는 Python 3.12.3이 자동으로 선택됩니다.
🧩 4. venv로 가상환경 만들기
pyenv로 버전을 지정했으면, 이제 그 위에 가상환경(venv)을 생성합니다.
cd ~/projects/myapp
python -m venv venv
source venv/bin/activate이제 프롬프트에 (venv)가 표시됩니다.
(venv) myapp %🧰 5. 패키지 설치 및 관리
# 예시) Flask 설치
pip install flask
# 설치된 목록 보기
pip list
# 현재 환경의 패키지 목록 저장
pip freeze > requirements.txt
# 다른 환경에서 복원
pip install -r requirements.txt🧠 6. VSCode에서 pyenv 가상환경 인식시키기
- VSCode 실행
- Command Palette (
⇧⌘P) →Python: Select Interpreter - 목록 중에서
venv/bin/python선택
이제 VSCode가 해당 가상환경을 자동으로 인식하고 실행합니다.
⚡ 7. (선택) direnv로 자동 활성화하기
매번 source venv/bin/activate를 입력하기 귀찮다면direnv를 이용해 폴더 진입 시 자동으로 활성화되게 할 수 있습니다.
brew install direnv
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc그리고 프로젝트 폴더에 .envrc 파일을 만들어 아래 내용 추가:
layout python3이제 폴더에 진입하면 자동으로 (venv)가 활성화됩니다 🚀
🧾 8. pyenv + venv 정리
| 구분 | 명령어 | 설명 |
|---|---|---|
| pyenv 설치 | brew install pyenv |
Python 버전 관리 도구 설치 |
| Python 버전 설치 | pyenv install 3.12.3 |
원하는 버전 설치 |
| 버전 적용 | pyenv local 3.12.3 |
현재 폴더에 버전 지정 |
| 가상환경 생성 | python -m venv venv |
독립 환경 생성 |
| 가상환경 활성화 | source venv/bin/activate |
가상환경 진입 |
| 비활성화 | deactivate |
가상환경 종료 |
| 패키지 저장 | pip freeze > requirements.txt |
패키지 버전 기록 |
| 패키지 복원 | pip install -r requirements.txt |
동일 환경 복원 |
🚀 마무리
pyenv와 venv를 함께 사용하면
- 프로젝트별 Python 버전 관리
- 패키지 충돌 방지
- 협업 환경 재현
이 모두 깔끔하게 해결됩니다.
✅ 추천 조합:
pyenv로 버전 관리 +venv로 패키지 관리
→ “Python 환경의 정석 세팅”입니다.
📘 다음 글 예고:
pyenv-virtualenv플러그인을 이용해 가상환경을 자동 관리하는 방법poetry를 통한 의존성 및 빌드 관리 자동화
댓글