pyenv 파이썬 버전 관리

pyenv 파이썬 버전 관리
개발을 하다 보면 프로젝트 A는 파이썬 3.8, 프로젝트 B는 3.10을 써야 하는 등 각기 다른 파이썬 버전을 다루어야 할 때가 많습니다. 시스템에 설치된 파이썬 하나만 사용하다 보면 버전 충돌로 골치 아픈 경험, 다들 한 번쯤 있으실 텐데요.

이런 혼란을 깔끔하게 정리해 줄 마법 같은 도구가 바로 pyenv입니다. pyenv는 다양한 파이썬 버전을 쉽게 설치하고, 프로젝트별로 원하는 버전을 자유롭게 지정할 수 있게 해주는 "파이썬 버전 관리자"입니다.

이 글에서는 우분투(Ubuntu/WSL) 환경을 기준으로 pyenv의 설치부터 프로젝트에 적용하는 실전 팁까지, 블로그에 바로 올릴 수 있는 형태로 완벽하게 정리해 드립니다.

1. pyenv 설치하기

1단계: 필수 프로그램 설치

pyenv는 소스 코드를 직접 컴파일하여 파이썬을 설치합니다. 이를 위해 필요한 빌드 도구들을 먼저 설치해주어야 합니다.

sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git

2단계: pyenv 설치

아래 명령어를 터미널에 입력하면 간단하게 pyenv를 설치할 수 있습니다.

curl https://pyenv.run | bash

3단계: 셸 환경 설정

설치가 끝나면, 터미널을 열 때마다 pyenv가 자동으로 실행되도록 셸 설정 파일(.bashrc)에 몇 가지 내용을 추가해야 합니다. 아래 명령어를 순서대로 입력하세요.

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

마지막으로, 아래 명령어를 실행하거나 터미널을 껐다가 다시 켜서 설정을 적용합니다.

exec "$SHELL"

2. pyenv 기본 사용법

설치가 완료되었으니 이제 pyenv의 핵심 기능들을 사용해봅시다.

설치 가능한 파이썬 버전 확인

어떤 버전의 파이썬을 설치할 수 있는지 전체 목록을 확인합니다.

pyenv install --list

원하는 파이썬 버전 설치

목록에서 원하는 버전을 골라 설치합니다. (컴파일 과정이 있어 시간이 다소 걸릴 수 있습니다.)

# 예시: 파이썬 3.10.10 버전 설치
pyenv install 3.10.10

설치된 버전 목록 확인

pyenv를 통해 현재 내 컴퓨터에 설치된 모든 파이썬 버전 목록을 봅니다.

pyenv versions

system: 시스템에 기본으로 설치된 파이썬

3.10.10: 방금 pyenv로 설치한 파이썬

현재 사용 중인 버전 앞에는 * (별표)가 표시됩니다.

3. 프로젝트에 적용하기 (가상 환경)

pyenv의 진짜 강력함은 프로젝트별로 독립된 개발 환경을 만드는 데서 나옵니다.

특정 버전으로 가상 환경 만들기

방금 설치한 3.10.10 버전을 기반으로 하는, my-project-env라는 이름의 독립된 가상 환경을 만듭니다.

pyenv virtualenv 3.10.10 my-project-env

가상 환경 활성화 및 비활성화

프로젝트 작업을 시작할 때 가상 환경을 켜고, 끝났을 때 끌 수 있습니다.

# 활성화
pyenv activate my-project-env

# 비활성화
pyenv deactivate
활성화하면 터미널 프롬프트 앞에 (my-project-env)와 같이 현재 가상 환경의 이름이 표시됩니다.

꿀팁: 폴더별 가상 환경 자동 활성화

매번 activate 명령어를 치는 것은 번거롭습니다. 프로젝트 폴더에 들어갔을 때 자동으로 특정 가상 환경이 활성화되도록 설정할 수 있습니다.

1. 내 프로젝트 폴더로 이동

cd ~/my_project_folder

2. 이 폴더에서는 'my-project-env'를 사용하겠다고 지정

pyenv local my-project-env

이렇게 하면 폴더 안에 .python-version 파일이 생성되면서, 이 폴더에 들어오면 자동으로 my-project-env가 활성화되고, 폴더를 빠져나가면 비활성화됩니다.

---

추가적으로

pyenv와 venv는 파이썬 개발 환경을 격리하는, 서로 다른 목적을 가진 도구입니다. pyenv는 파이썬 '버전' 자체를 관리하고, venv는 특정 파이썬 버전 안에서 '패키지'들을 관리합니다.

많은 경우 이 둘을 함께 사용하며, 가장 이상적인 조합으로 아래 내용을 참고해서 사용 할 수 있습니다.

사용 방법

pyenv로 원하는 버전 활성화하기

pyenv shell 또는 pyenv local 명령어를 사용하여 python -m venv를 실행할 기반이 될 파이썬 버전을 지정합니다.

# 예시: 현재 터미널에서만 3.10.10 버전을 활성화
pyenv shell 3.10.10

활성화된 버전 확인

python --version 명령어로 현재 터미널의 파이썬이 방금 지정한 버전으로 바뀌었는지 확인합니다.

python --version
# Python 3.10.10

python -m venv로 가상 환경 생성

이제 표준 venv 명령어를 실행하면, 활성화된 3.10.10 버전을 기반으로 하는 가상 환경이 생성됩니다.

python -m venv my-project-env

이 방법은 pyenv-virtualenv 플러그인을 사용하지 않고도, pyenv의 버전 관리 기능과 파이썬의 표준 가상 환경 기능을 조합하여 활용하는 좋은 예시입니다.