pyenv: Python 버전 관리의 효율적인 도구

Python 개발을 하다 보면 프로젝트마다 다른 버전의 Python을 사용해야 하는 상황이 자주 발생합니다. 이럴 때 pyenv는 시스템에 여러 버전의 Python을 설치하고 프로젝트별로 쉽게 전환할 수 있게 해주는 강력한 도구입니다. 이 글에서는 pyenv의 설치부터 실제 프로젝트에서의 활용 방법까지 상세히 알아보겠습니다.

시스템에서 Python이 설치가 되어있는지, 어디에 설치되어있는지, 버전은 몇으로 설치되어있는지 체크를 먼저 아래와 같이 해봅니다.

$ which python
/usr/bin/python

$ python -V
Python 2.7.12

이렇게 특정 버전 하나가 시스템에 설치된 경우에 Pyenv를 통해서 여러 버전을 함께 관리를 해보는 것을 추천합니다.

pyenv란?

pyenv는 다양한 Python 버전을 관리하고 전환할 수 있게 해주는 도구로, 시스템 Python을 건드리지 않고도 여러 버전의 Python을 설치하고 사용할 수 있습니다. 특히 프로젝트별로 다른 Python 버전이 필요할 때 매우 유용합니

pyenv 설치하기

macOS에서 설치

Homebrew를 이용하여 간단하게 설치할 수 있습니다:
(만약 아래 brew 도 설치 안되었다면, https://brew.sh/ 에서 설치를 먼저 하세요. )

$ brew update
$ brew install pyenv

Linux에서 설치

자동 설치 스크립트를 사용하여 설치할 수 있습니다:

$ curl https://pyenv.run | bash

또는 GitHub 저장소를 직접 클론하여 설치할 수도 있습니다:

$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv

설치 후 환경 설정

pyenv를 설치한 후에는 쉘 환경 설정 파일에 다음 내용을 추가해야 합니다:

Bash를 사용하는 경우 (~/.bashrc 또는 ~/.bash_profile):

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

Zsh를 사용하는 경우 (~/.zshrc):

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

설정 후 쉘을 재시작하거나 설정 파일을 다시 로드합니다:

$ source ~/.bashrc  # 또는 ~/.zshrc

pyenv 기본 사용법

사용 가능한 Python 버전 확인

$ pyenv install --list

이 명령어는 설치 가능한 모든 Python 버전을 보여줍니다.

특정 버전의 Python 설치

$ pyenv install 3.11.12

위 명령어는 Python 3.11.12 버전을 설치합니다.

설치된 Python 버전 확인

$ pyenv versions

이 명령어는 현재 설치된 모든 Python 버전과 현재 활성화된 버전을 보여줍니다.

Python 버전 설정하기

글로벌(global) 버전 설정

시스템 전체에서 사용할 기본 Python 버전을 설정합니다:

$ pyenv global 3.9.7

이제 어디서든 `python` 명령어를 실행하면 Python 3.9.7이 사용됩니다.

로컬(local) 버전 설정

특정 디렉토리(프로젝트)에서만 사용할 Python 버전을 설정합니다:

$ cd my_project
$ pyenv local 3.8.12

이 설정은 해당 디렉토리에 `.python-version` 파일을 생성하여 저장됩니다. 이 디렉토리 내에서는 Python 3.8.12가 사용됩니다.

쉘(shell) 버전 설정

현재 쉘 세션에서만 임시로 사용할 Python 버전을 설정합니다:

$ pyenv shell 3.7.12

이 설정은 쉘을 종료하면 사라집니다.

설정 우선순위

pyenv는 다음 순서로 Python 버전을 결정합니다:

PYENV_VERSION 환경 변수 (pyenv shell로 설정)
.python-version 파일 (pyenv local로 설정)
글로벌 설정 (pyenv global로 설정)

pyenv와 virtualenv 함께 사용하기

pyenv-virtualenv 플러그인을 사용하면 pyenv와 virtualenv를 함께 사용할 수 있습니다.

pyenv-virtualenv 설치

macOS:

$ brew install pyenv-virtualenv

Linux:

$ git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

쉘 설정 파일에 다음 내용을 추가합니다:

eval "$(pyenv virtualenv-init -)"

가상환경 생성 및 사용

특정 Python 버전으로 가상환경 생성:

$ pyenv virtualenv 3.9.7 my-project-env

가상환경 활성화:

$ pyenv activate my-project-env

또는 로컬 환경으로 설정:

$ cd my-project
$ pyenv local my-project-env

가상환경 비활성화:

$ pyenv deactivate

실제 프로젝트에서의 pyenv 활용 사례

1. 레거시 프로젝트 유지보수

Python 2.7로 작성된 레거시 프로젝트를 유지보수하면서 동시에 Python 3.9 기반의 새 프로젝트를 개발해야 하는 경우:

# 레거시 프로젝트 디렉토리
$ cd ~/projects/legacy-project
$ pyenv local 2.7.18
$ pyenv virtualenv 2.7.18 legacy-env
$ pyenv local legacy-env

# 새 프로젝트 디렉토리
$ cd ~/projects/new-project
$ pyenv local 3.9.7
$ pyenv virtualenv 3.9.7 new-project-env
$ pyenv local new-project-env

2. 프레임워크 호환성 테스트

Django 애플리케이션이 여러 Python 버전에서 제대로 작동하는지 테스트하는 경우:

# Python 3.7에서 테스트
$ pyenv shell 3.7.12
$ python -m pytest

# Python 3.8에서 테스트
$ pyenv shell 3.8.12
$ python -m pytest

# Python 3.9에서 테스트
$ pyenv shell 3.9.7
$ python -m pytest

3. 데이터 사이언스 프로젝트

데이터 사이언스 프로젝트에서 특정 라이브러리 버전과 호환되는 Python 환경 구성:

$ pyenv virtualenv 3.8.12 data-science-env
$ pyenv activate data-science-env
$ pip install numpy pandas scikit-learn tensorflow

4. CI/CD 파이프라인 구성

CI/CD 파이프라인에서 여러 Python 버전으로 테스트를 자동화하는 경우 (.github/workflows/python-tests.yml 예시):

name: Python Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.7, 3.8, 3.9]
    
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pytest
        pip install -r requirements.txt
    - name: Test with pytest
      run: |
        pytest

pyenv 활용 팁과 모범 사례

프로젝트별 .python-version 파일 버전 관리: 프로젝트의 Python 버전 요구사항을 명확히 하기 위해 .python-version 파일을 Git에 포함시키세요.
requirements.txt와 함께 사용: 가상환경과 함께 requirements.txt 파일을 사용하여 패키지 의존성을 관리하세요.
자동 가상환경 활성화: pyenv-virtualenv의 자동 활성화 기능을 활용하면 디렉토리 진입 시 자동으로 가상환경이 활성화됩니다.
pyenv 업데이트: 정기적으로 pyenv를 업데이트하여 최신 Python 버전을 사용할 수 있게 하세요.

# pyenv 업데이트
$ cd $(pyenv root)
$ git pull

문제 해결

Python 설치 실패 시: 필요한 의존성 패키지가 설치되어 있는지 확인하세요.

Ubuntu/Debian:

$ sudo apt-get 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 python-openssl

CentOS/RHEL:

$ sudo yum install -y gcc zlib-devel bzip2 bzip2-devel readline-devel \
sqlite sqlite-devel openssl-devel xz xz-devel libffi-devel

결론

pyenv는 여러 Python 버전을 관리하고 프로젝트별로 격리된 환경을 구성하는 데 매우 유용한 도구입니다. 특히 여러 프로젝트를 동시에 진행하거나, 다양한 Python 버전과의 호환성을 테스트해야 하는 개발자에게 필수적인 도구라고 할 수 있습니다.

pyenv와 virtualenv를 함께 사용하면 더욱 강력한 개발 환경을 구성할 수 있으며, 이를 통해 의존성 충돌 없이 깔끔하고 효율적인 Python 개발이 가능해집니다. 이 글에서 소개한 방법과 사례를 참고하여 여러분의 개발 환경을 최적화해보세요!

참고 자료:

https://realpython.com/intro-to-pyenv/#using-the-pyenv-installer

게시됨

2025년 04월 27일

카테고리

Python

작성자

choonzang

태그:

pyenv, 버전관리도구