맥에서 pyenv와 venv를 사용해 파이썬 가상환경을 구축하려다, 파이썬 버전이 뒤엉키고 프로젝트마다 패키지 충돌이 발생해 여러 번 좌절하셨나요? 분명 설치는 했는데 막상 사용하려 하면 `python` 명령어가 엉뚱한 버전을 가리키거나, 라이브러리 설치 시 알 수 없는 오류가 뜨는 경험은 흔한 문제입니다.
이런 문제는 파이썬 버전 관리 도구와 가상환경 생성 도구의 역할을 명확히 이해하고, 이들을 통합하는 과정에서 발생하는 오해 때문에 비롯됩니다.
이 글에서는 pyenv와 pyenv-virtualenv를 활용하여 맥 환경에서 파이썬 가상환경을 엉킴 없이, 일관되고 효율적으로 관리하는 5단계 방법을 명확히 제시합니다.
– pyenv와 pyenv-virtualenv를 함께 사용하여 파이썬 버전과 가상환경을 통합 관리합니다.
– 각 프로젝트별로 독립된 가상환경을 구축해 패키지 충돌을 원천 차단합니다.
– 5단계 가이드라인을 통해 맥 환경에서 안정적인 파이썬 개발 환경을 구축하는 방법을 제시합니다.
맥에서 pyenv를 이용해 파이썬 버전 관리와 venv 가상환경을 복잡함 없이 깔끔하게 설정하는 방법을 알려드립니다.
pyenv와 pyenv-virtualenv, 왜 함께 써야 할까?
많은 맥 사용자분들이 파이썬 개발 환경을 설정하며 깊은 고민에 빠집니다. 여러 프로젝트를 진행하다 보면, 특정 프로젝트는 파이썬 3.8을, 다른 프로젝트는 3.10을 요구하는 상황이 빈번합니다. 이때 파이썬 공식 홈페이지에서 받은 인스톨러나 Homebrew로 설치한 단일 파이썬만으로는 이 복잡한 요구사항을 절대 만족시킬 수 없습니다. 이로 인해 `pip install` 과정에서 원치 않는 패키지 충돌이 발생하거나, `python` 명령어가 엉뚱한 버전을 가리키는 문제가 발생하곤 합니다.
pyenv는 이러한 파이썬 버전 꼬임을 깔끔하게 해결해주는 역할을 합니다. 여러 파이썬 버전을 시스템에 설치하고 필요에 따라 전환할 수 있도록 돕는 것이죠. 하지만 pyenv만으로는 각 버전별 독립적인 패키지 환경을 제공하지 못합니다. 여기서 pyenv-virtualenv가 등장합니다. 이 플러그인은 pyenv가 관리하는 특정 파이썬 버전을 기반으로, 완벽하게 격리된 가상환경을 생성하고 관리하는 기능을 더해줍니다. 이 둘을 함께 사용하면, 마치 독립된 작업 공간을 여러 개 두는 것처럼 프로젝트별 맞춤형 환경을 손쉽게 구축할 수 있습니다.
| 구분 | pyenv | pyenv-virtualenv |
|---|---|---|
| 주요 기능 | 시스템에 여러 파이썬 버전 설치 및 전환 | pyenv가 관리하는 파이썬 버전을 기반으로 가상환경 생성 및 관리 |
| 해결 문제 | 다중 파이썬 버전 공존 및 전환 | 프로젝트별 패키지 충돌 및 격리 환경 필요 |
| 특징 | 파이썬 바이너리 자체를 관리 | 가상환경을 pyenv의 셸 명령어로 통합 관리 |
맥에 pyenv와 pyenv-virtualenv 설치 및 기본 설정
본격적인 설치에 앞서, 맥 환경에는 Homebrew와 Xcode Command Line Tools가 먼저 설치되어 있어야 합니다. 이 두 도구는 맥에서 개발 환경을 구축할 때 90% 이상의 상황에서 필수적으로 사용됩니다. 만약 아직 설치하지 않았다면, 터미널에 `xcode-select –install` (Xcode Command Line Tools)과 `/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)”` (Homebrew)를 입력하여 설치를 완료해야 합니다.
이제 pyenv와 pyenv-virtualenv를 설치하고 셸 환경을 설정해봅시다. 이 과정은 약 5분 정도 소요되며, 한 번만 제대로 설정해두면 향후 파이썬 개발 환경 관리의 80% 이상이 해결됩니다. 아래 단계를 따라 진행하면 됩니다.
- Homebrew를 이용한 pyenv 설치 — 터미널에 `brew install pyenv`를 입력합니다.
- Homebrew를 이용한 pyenv-virtualenv 설치 — 이어서 `brew install pyenv-virtualenv`를 입력합니다.
- 셸 환경 설정 (Bash 또는 Zsh) — 사용하는 셸에 따라 `.bashrc`, `.bash_profile`, `.zshrc` 파일 중 하나를 열어 다음 내용을 추가합니다. (macOS Catalina 이후 기본 셸은 Zsh입니다.)
`echo ‘eval “$(pyenv init –path)”‘ >> ~/.zshrc`
`echo ‘eval “$(pyenv init -)”‘ >> ~/.zshrc`
`echo ‘eval “$(pyenv virtualenv-init -)”‘ >> ~/.zshrc` - 설정 적용 — 변경된 셸 설정을 즉시 적용하기 위해 `source ~/.zshrc` 또는 터미널을 다시 시작합니다.
- 설치 확인 — `pyenv versions` 명령어를 입력했을 때, `system` 외에 아무것도 뜨지 않으면 정상입니다. `pyenv virtualenvs` 명령어 또한 실행 가능해야 합니다.
파이썬 버전 설치 및 가상환경 생성 핵심 5단계
pyenv와 pyenv-virtualenv의 설치가 완료되었다면, 이제 실제 프로젝트에서 사용할 파이썬 버전을 설치하고, 그 위에 독립적인 가상환경을 구축할 차례입니다. 이 과정은 각 프로젝트의 시작점이 되며, 올바르게 설정하면 겪었던 대부분의 패키지 충돌 문제가 사라집니다. 다음 5단계 과정을 통해 깔끔한 환경을 만들어보겠습니다.
특히 여기서 중요한 것은 가상환경 이름을 명확하게 지정하는 것입니다. 예를 들어, 특정 프로젝트명과 파이썬 버전을 결합하여 `myproject-3.9.10`과 같이 명명하면, 나중에 여러 가상환경이 생겼을 때도 혼동 없이 관리할 수 있습니다.
- 사용 가능한 파이썬 버전 확인 — `pyenv install –list` 명령어로 설치 가능한 파이썬 버전을 확인합니다. 이 목록은 수십 가지가 넘을 수 있습니다.
- 원하는 파이썬 버전 설치 — 예를 들어 파이썬 3.9.10 버전을 설치하려면 `pyenv install 3.9.10`을 입력합니다. 설치에는 3분에서 5분 정도 소요될 수 있습니다.
- 특정 파이썬 버전 기반 가상환경 생성 — 설치된 파이썬 3.9.10을 기반으로 `myproject-env`라는 이름의 가상환경을 생성하려면 `pyenv virtualenv 3.9.10 myproject-env`를 실행합니다.
- 프로젝트 디렉토리에서 가상환경 지정 — 프로젝트 루트 디렉토리로 이동한 후 `pyenv local myproject-env` 명령어를 입력합니다. 이 명령을 실행하면 해당 디렉토리에 `.python-version` 파일이 생성되며, 앞으로 이 디렉토리에서는 `myproject-env` 가상환경이 자동으로 활성화됩니다.
- 가상환경 확인 및 패키지 설치 — `pyenv versions` 명령어로 현재 활성화된 가상환경을 확인하고, `pip install 필요한_패키지`와 같이 필요한 라이브러리를 설치합니다. 이제 설치되는 모든 패키지는 `myproject-env` 내부에만 존재합니다.
프로젝트별 가상환경 활성화 및 관리 팁
`pyenv local` 명령어를 통해 `.python-version` 파일이 생성되면, 해당 디렉토리로 이동할 때마다 설정한 가상환경이 자동으로 활성화됩니다. 이는 매번 `source activate` 명령어를 입력하는 번거로움을 덜어주어 개발 생산성을 크게 향상시킵니다. 터미널 프롬프트에 가상환경 이름이 표시되는 것을 확인하여 제대로 활성화되었는지 쉽게 알 수 있습니다.
작업이 끝나거나 다른 프로젝트로 전환할 때는 `pyenv deactivate` 명령어를 사용해 현재 가상환경을 비활성화하고, 시스템 파이썬 또는 `pyenv global`로 설정된 파이썬 환경으로 돌아갈 수 있습니다. 이처럼 pyenv와 pyenv-virtualenv의 강력한 통합 기능 덕분에, 엉킴 없는 깔끔한 파이썬 개발 환경 관리가 가능해집니다.
프로젝트를 다른 개발자와 공유하거나 Git과 같은 버전 관리 시스템을 사용할 때는 `.python-version` 파일을 함께 커밋하는 것이 좋습니다. 이를 통해 다른 팀원들도 같은 프로젝트 환경으로 손쉽게 전환할 수 있습니다. 단, 가상환경 내부의 `venv` 디렉토리 자체나 `site-packages` 내부는 커밋하지 않도록 `.gitignore` 파일에 반드시 추가해야 합니다. 가상환경은 언제든지 새로 생성할 수 있기 때문입니다.
맥에서 파이썬 가상환경을 깔끔하게 관리하려면 pyenv로 파이썬 버전을, pyenv-virtualenv로 가상환경을 각각 관리하고 통합하는 것이 핵심입니다. 이 글에서 제시한 5단계 설치 및 설정 과정을 통해 파이썬 버전 꼬임과 패키지 충돌로부터 완전히 해방될 수 있습니다.
지금 바로 적용해 보세요.
- pyenv 공식 GitHub 저장소 — 파이썬 버전 관리를 위한 핵심 도구
- pyenv-virtualenv 공식 GitHub 저장소 — pyenv와 통합된 가상환경 관리 플러그인
- Homebrew 공식 웹사이트 — macOS용 패키지 관리자의 표준
동영상으로 보는 맥 파이썬 가상환경 pyenv venv 깔끔하게 설정
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
자주 묻는 질문
Q. venv나 conda도 있는데, 왜 굳이 pyenv와 pyenv-virtualenv를 함께 사용해야 하나요?
A. pyenv는 다양한 Python 버전을 Mac에 깔끔하게 설치하고 손쉽게 전환할 수 있게 해주는 강력한 도구입니다. 여기에 pyenv-virtualenv는 특정 Python 버전에 종속된 가상환경을 생성하여 프로젝트별 의존성을 완벽하게 분리합니다. 이 조합은 여러 프로젝트에서 각기 다른 Python 버전과 라이브러리를 사용해야 할 때 버전 충돌 없이 깔끔하게 개발 환경을 관리할 수 있게 돕습니다.
Q. pyenv 설치 후에도 python 명령어를 입력하면 시스템 Python이나 Homebrew Python이 실행됩니다. 무엇이 문제인가요?
A. 이는 pyenv가 쉘에 제대로 초기화되지 않았거나 PATH 환경 변수가 올바르게 설정되지 않았을 가능성이 큽니다. .zshrc 또는 .bash_profile 파일에 `eval “$(pyenv init -)”`와 `eval “$(pyenv virtualenv-init -)”` 라인이 추가되어 있고, pyenv shims 디렉토리가 PATH의 가장 앞에 오도록 설정되었는지 확인하세요. 변경 사항 적용을 위해 쉘을 재시작하거나 `source` 명령어로 파일을 다시 로드해야 합니다.
Q. pyenv-virtualenv로 가상환경을 만들었는데, 어떻게 활성화하고 사용해야 하나요?
A. 먼저 `pyenv install 3.x.x`로 원하는 Python 버전을 설치한 후, `pyenv virtualenv 3.x.x my-project-env` 명령어로 가상환경을 생성합니다. 이렇게 생성된 가상환경은 프로젝트 디렉토리로 이동하여 `pyenv local my-project-env`를 실행하면 해당 디렉토리에서 자동으로 활성화됩니다. 별도의 `activate` 명령 없이 `cd` 명령으로 디렉토리에 진입하기만 하면 됩니다.
Q. 여러 가상환경을 만들었을 때, 특정 프로젝트에서 원하는 가상환경으로 어떻게 전환하나요?
A. pyenv는 `local`, `global`, `shell` 세 가지 스코프를 제공하여 가상환경을 관리합니다. 특정 프로젝트 디렉토리에서만 가상환경을 사용하려면 해당 디렉토리에서 `pyenv local my-project-env` 명령을 사용하세요. 그러면 해당 디렉토리에 `.python-version` 파일이 생성되어 디렉토리 진입 시 자동으로 지정된 가상환경이 활성화됩니다.
📚 함께 읽으면 좋은 글