pyenv 완벽 가이드: Python 버전 관리부터 가상환경까지

1 1. pyenv란?
2 2. pyenv 설치 방법
3 3. Python 버전 관리
4 4. virtualenv와 함께 사용하기
5 5. pyenv를 사용할 때의 주의사항
6 6. 정리와 다음 단계
- 6.1 pyenv 활용 정리
- 6.2 다음 단계

1. pyenv란?

Python 개발자에게는 프로젝트마다 서로 다른 버전의 Python을 사용해야 하는 일이 자주 있습니다. 그때 도움이 되는 것이 “pyenv”입니다. pyenv는 여러 Python 버전을 관리하고, 프로젝트별로 다른 버전으로 쉽게 전환할 수 있는 도구입니다.

Python 버전 관리의 과제

Python 개발을 진행하다 보면 여러 프로젝트에서 서로 다른 Python 버전이 필요할 때가 있습니다. 예를 들어 어떤 프로젝트에서는 Python 3.9를 사용하고, 다른 프로젝트에서는 Python 2.7이 필요할 수 있습니다. 일반적으로 시스템에 설치되어 있는 Python 버전은 하나뿐이라 버전 전환이 번거롭습니다. 이 문제를 해결해 주는 것이 pyenv입니다.

pyenv의 장점

pyenv를 사용하면 다음과 같은 이점이 있습니다:

간편한 버전 전환: pyenv를 사용하면 시스템 전체 또는 프로젝트별로 Python 버전을 손쉽게 전환할 수 있습니다.
여러 버전 관리: 시스템에 설치된 여러 Python 버전을 하나의 명령으로 관리할 수 있습니다. 이를 통해 프로젝트별 의존성과 버전 차이에 유연하게 대응할 수 있습니다.
Windows를 제외한 다양한 OS 지원: macOS와 Linux 등 여러 OS에서 사용 가능합니다.

pyenv의 동작 원리

pyenv는 Python 버전마다 별도의 디렉터리를 만들고, 그 안에 각 버전의 Python을 설치합니다. 사용자는 pyenv global와 pyenv local 명령을 사용해 시스템 전체나 특정 프로젝트에서 사용할 버전을 지정할 수 있습니다.

2. pyenv 설치 방법

개요

pyenv를 사용하려면 먼저 시스템에 설치해야 합니다. 이 섹션에서는 macOS와 Linux를 대상으로, pyenv의 설치 절차를 설명합니다. Windows 환경에서는 pyenv가 지원되지 않으므로, 다른 수단(WSL이나 Anaconda 등)을 사용하는 것을 권장합니다.

macOS에서의 설치 방법

macOS에서는 Homebrew를 사용해 pyenv를 간단히 설치할 수 있습니다. Homebrew는 macOS용 패키지 관리 도구로, 다양한 소프트웨어를 손쉽게 설치할 수 있는 편리한 도구입니다. 아래 절차에 따라 설치를 진행하세요.

Homebrew 설치 확인 먼저, Homebrew가 시스템에 설치되어 있는지 확인합니다. 터미널을 열고 아래 명령을 실행합니다.

   brew --version

버전 정보가 표시되면, Homebrew는 이미 설치된 것입니다. 설치되어 있지 않은 경우, 공식 사이트(Homebrew 공식 사이트)에서 설치 절차를 확인하세요.

pyenv 설치 Homebrew가 설치되어 있는 경우, 다음 명령을 실행해 pyenv를 설치합니다.

   brew install pyenv

설치가 완료되면, 다음 단계로 진행합니다.

환경 변수 설정 pyenv를 사용하려면 셸의 환경 변수를 설정해야 합니다. 보통 .bash_profile이나.zshrc에 설정을 추가합니다. 터미널에서 아래 명령을 실행해 환경 변수를 설정합니다.

   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
   echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile

.zshrc를 사용 중이라면, .bash_profile이 아니라 .zshrc에 이 줄들을 추가하세요. 설정을 마쳤다면, 터미널을 재시작하거나 아래 명령으로 설정을 반영하세요.

   source ~/.bash_profile

설치 확인 설정을 마쳤다면, 아래 명령을 실행해 pyenv가 올바르게 설치되었는지 확인합니다.

   pyenv --version

버전 번호가 표시되면, pyenv는 올바르게 설치된 것입니다.

Linux에서의 설치 방법

Linux 환경에서도 기본적으로 macOS와 동일한 절차로 pyenv를 설치할 수 있지만, 패키지 매니저로 apt나 yum을 사용하는 것이 일반적입니다. 아래는 Ubuntu에서의 설치 절차입니다.

필요 패키지 설치 pyenv를 설치하기 전에, 의존 패키지를 설치해야 합니다. 아래 명령을 실행해 필요한 도구를 설치합니다.

   sudo apt update
   sudo apt install -y 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 git

pyenv 설치 Git을 사용해, pyenv의 리포지토리를 클론하여 설치합니다.

   curl https://pyenv.run | bash

환경 변수 설정 pyenv를 활성화하기 위해, .bashrc나 .zshrc에 아래 설정을 추가합니다.

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

설정을 반영하기 위해, 터미널을 재시작하거나 source ~/.bashrc를 실행합니다.

설치 확인 아래 명령을 실행해, pyenv가 올바르게 설치되었는지 확인합니다.

   pyenv --version

문제 해결

pyenv 설치 중 오류가 발생한 경우, 의존 라이브러리가 부족했을 가능성이 있습니다. 특히 Linux에서는 시스템에 따라 필요한 라이브러리가 달라질 수 있으므로, 공식 문서를 참고하여 적절한 라이브러리를 설치해 주세요.

3. Python 버전 관리

pyenv를 설치한 후에는 실제로 Python 버전을 관리하는 방법을 배워야 합니다. 이 섹션에서는 pyenv를 사용하여 Python 버전을 설치하고 전환하는 절차를 설명합니다.

Python 버전 설치

pyenv에서는 간단하게 서로 다른 Python 버전을 설치할 수 있습니다. 예를 들어 한 프로젝트에서는 Python 3.8을, 다른 프로젝트에서는 Python 3.9를 사용하고 싶다면 다음과 같이 각 버전을 설치할 수 있습니다.

버전 목록 확인 먼저, pyenv에서 사용할 수 있는 Python 버전 목록을 확인합니다. 아래 명령으로 설치 가능한 버전이 목록으로 표시됩니다.

   pyenv install --list

이렇게 하면 pyenv가 지원하는 모든 Python 버전이 표시되며, 필요한 버전을 선택할 수 있습니다.

Python 버전 설치 특정 버전을 설치하려면 아래 명령을 사용합니다.

   pyenv install 3.9.1

이 명령으로 Python 3.9.1이 시스템에 설치됩니다. 여러 버전이 필요한 경우 각 버전을 개별적으로 설치하면 됩니다.

Python 버전 전환

pyenv를 사용하면 설치한 여러 Python 버전 사이를 쉽게 전환할 수 있습니다. 이를 통해 프로젝트마다 다른 Python 버전을 사용할 수 있으며, 환경별 의존성 문제를 피할 수 있습니다.

시스템 전체 버전 전환 시스템 전체에서 사용할 Python 버전을 변경하려면 아래 명령을 사용합니다.

   pyenv global 3.9.1

이 명령은 시스템 전체에서 Python 3.9.1이 사용되도록 설정합니다. 모든 디렉터리에서 이 버전이 적용됩니다.

프로젝트별 버전 전환 특정 디렉터리에서만 Python 버전을 변경하려면 pyenv local 명령을 사용합니다. 이 명령은 프로젝트마다 다른 버전을 설정하고자 할 때 유용합니다.

   pyenv local 3.8.0

이 명령을 실행하면 현재 디렉터리에서만 Python 3.8.0이 사용되고, 다른 디렉터리에서는 pyenv global로 설정된 버전이 적용됩니다.

현재 버전 확인 현재 시스템 또는 프로젝트에서 사용 중인 Python 버전을 확인하려면 다음 명령을 사용합니다.

   pyenv version

이 명령으로 시스템 전체 또는 로컬 디렉터리에 설정된 Python 버전을 확인할 수 있습니다.

버전 제거

프로젝트가 더 이상 필요 없거나 실수로 설치한 Python 버전을 삭제해야 하는 경우, pyenv에서는 쉽게 버전을 제거할 수 있습니다.

제거 방법 설치한 Python 버전을 삭제하려면 아래 명령을 실행합니다.

   pyenv uninstall 3.9.1

이 명령으로 Python 3.9.1이 시스템에서 삭제됩니다.

4. virtualenv와 함께 사용하기

pyenv는 Python 버전 관리에 강력한 지원을 제공하지만, Python 프로젝트에서 의존성을 보다 효율적으로 관리하려면 virtualenv(가상 환경)과 함께 사용하는 것이 일반적입니다. 이 섹션에서는 pyenv와 virtualenv를 어떻게 함께 사용하는지, 그리고 그 편의성에 대해 설명합니다。

virtualenv란？

virtualenv는 Python 프로젝트별로 독립적인 가상 환경을 만들고, 라이브러리와 패키지의 의존성을 격리하기 위한 도구입니다. 이를 통해 동일한 시스템에서 여러 프로젝트가 서로 다른 버전의 패키지를 사용하더라도 상호 간섭 없이 개발을 진행할 수 있습니다。 예를 들어, 프로젝트 A에서는 requests 버전 2.0을 사용하고, 프로젝트 B에서는 버전 3.0을 사용하는 경우에도 각 프로젝트마다 독립적인 환경을 구축할 수 있습니다。

pyenv와 virtualenv의 차이

pyenv는 주로 Python의버전 관리에 초점을 맞춘 도구로, 시스템 전체 또는 프로젝트별로 서로 다른 Python 버전을 설치하고 전환할 수 있습니다. 반면, virtualenv는 Python의라이브러리와 패키지 의존성을 가상 환경 내에서 관리하는 도구입니다。 pyenv와virtualenv를 함께 사용하면 다음과 같은 이점이 있습니다：

여러 Python 버전 관리: pyenv를 사용해 서로 다른 버전의 Python을 설치하고, 프로젝트별로 최적의 버전을 설정할 수 있습니다.
라이브러리 의존성을 프로젝트별로 관리: virtualenv로 프로젝트마다 가상 환경을 만들어 라이브러리와 패키지의 충돌을 방지할 수 있습니다.

pyenv-virtualenv 설치

pyenv에 더해、pyenv-virtualenv라는 플러그인을 설치하면 가상 환경의 생성과 관리를 더욱 쉽게 할 수 있습니다. 다음 절차로 설치할 수 있습니다。

설치 절차 pyenv-virtualenv는 다음 명령으로 설치할 수 있습니다。

   brew install pyenv-virtualenv

Linux 사용자라면 다음 명령으로 설치할 수 있습니다。

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

환경 변수 설정 설치 후 셸 설정 파일에 다음 줄을 추가하여 pyenv-virtualenv를 활성화합니다。

   echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile
   source ~/.bash_profile

가상 환경 생성

pyenv-virtualenv를 사용하면 Python 버전별로 가상 환경을 만들 수 있습니다. 예를 들어, Python 3.8.0을 사용하는 가상 환경을 만들려면 다음과 같이 명령을 실행합니다。

pyenv virtualenv 3.8.0 my_project_env

이 명령을 실행하면 Python 3.8.0을 기반으로 한 가상 환경my_project_env가 생성됩니다。

가상 환경 전환

생성한 가상 환경을 프로젝트에서 사용하려면 pyenv local 명령을 사용합니다。

pyenv local my_project_env

이 명령을 실행하면 지정한 디렉터리에서 가상 환경my_project_env가 활성화됩니다. 다른 디렉터리에서는 전역으로 설정된 Python 버전이 사용됩니다。

가상 환경 삭제

가상 환경이 불필요해진 경우 pyenv uninstall 명령으로 쉽게 삭제할 수 있습니다。

pyenv uninstall my_project_env

virtualenv의 편의성

pyenv와 virtualenv를 조합하면 여러 프로젝트에서 Python 버전 관리와 라이브러리 의존성을 완전히 분리할 수 있습니다. 이를 통해 서로 다른 프로젝트 간 패키지 충돌 위험이 줄어들고, 각 프로젝트의 개발 환경을 안정적으로 유지할 수 있습니다。

5. pyenv를 사용할 때의 주의사항

pyenv와virtualenv를 활용하면, Python의 버전 관리와 환경 분리가 매우 효율적이지만, 사용할 때 주의해야 할 점과 문제가 발생하기 쉬운 부분이 있습니다. 여기서는, pyenv를 사용할 때의 흔한 문제와 그 해결 방법에 대해 자세히 설명합니다。

1. Windows에서의 지원이 제한적

pyenv는 기본적으로 macOS와 Linux에서의 사용이 권장됩니다. Windows 환경에서는 직접적인 지원이 없기 때문에 사용에 제한이 있습니다. Windows 사용자가pyenv를 사용하고 싶다면, 다음과 같은 옵션이 있습니다。

Windows Subsystem for Linux (WSL) 사용: WSL을 설치해 Linux 환경을 구축하고, 그 환경에서 pyenv를 이용하는 방법이 있습니다. 이를 통해 Windows에서도 Linux와 동일하게 pyenv를 사용할 수 있습니다.
Anaconda 사용: pyenv 대신 Anaconda를 사용하면 Windows 환경에서도 여러 Python 버전과 가상환경을 관리할 수 있습니다.

2. 의존 패키지 부족으로 인한 오류

특히 Linux 환경에서pyenv를 설치할 때, 필요한 의존 라이브러리가 설치되어 있지 않으면 오류가 발생할 수 있습니다. 다음과 같은 메시지가 표시된 경우, 의존 라이브러리를 설치해야 합니다。

WARNING: The Python bz2 extension was not compiled. Missing the bzip2 lib?

해결 방법：

필요한 의존 패키지(예: libbz2-dev 및 libssl-dev 등)를 설치하고, 다시 pyenv install 명령을 실행합니다. 의존 라이브러리를 설치하려면 아래 명령을 사용합니다.

   sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev

3. 기존 Python 버전과 pyenv의 충돌

시스템에 미리 설치되어 있는 Python과, pyenv로 관리하고 있는 Python 버전이 충돌할 수 있습니다. 이는 경로 설정에 오류가 있거나, 셸의 초기화 설정이 적절하지 않은 경우에 발생합니다。 해결 방법：

셸 초기화 파일(예: .bashrc나.zshrc)에 pyenv 관련 설정이 올바르게 추가되어 있는지 확인합니다. 특히 PATH 설정이 잘못되지 않았는지 확인하고, 다음 줄이 포함되어 있는지 확인합니다.

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

설정 후 터미널을 재시작하거나, source ~/.bashrc 명령으로 설정을 반영합니다。

4. 특정 Python 버전의 설치에 실패하는 경우

특정 버전의 Python을 설치하려 해도 설치에 실패할 수 있습니다. 이는 시스템에 필요한 빌드 도구나 라이브러리가 부족한 경우에 자주 발생합니다。 해결 방법：

부족한 의존 라이브러리를 설치한 뒤 다시 시도합니다. Linux 사용자라면 build-essential이나libssl-dev 등을 설치하고, 다시 pyenv install 명령을 실행합니다.

5. Python 버전 지정 실수

pyenv에서 Python의 버전을 지정할 때, 버전 입력 실수로 인해 오류가 발생할 수 있습니다. 특히 pyenv install 명령을 사용할 때에는, 지정하는 버전이 pyenv install --list로 확인할 수 있는 버전인지 확인하세요。 해결 방법：

버전 지정 실수를 방지하기 위해, 설치 가능한 버전을 미리 확인하고 올바른 버전 번호를 입력하는 것이 중요합니다.

6. 가상환경의 충돌

여러 가상환경을 사용하고 있는 경우, 같은 버전의 Python을 공유하는 환경들 사이에서 의존성이 충돌할 수 있습니다. 이 경우 패키지 버전이 충돌해 정상적으로 동작하지 않는 사례가 발생합니다。 해결 방법：

프로젝트마다 독립적인 가상환경을 만들고, virtualenv 또는 pyenv-virtualenv를 사용해 의존성을 완전히 분리합니다. 같은 Python 버전을 사용하더라도, 프로젝트마다 가상환경을 만들면 충돌을 피할 수 있습니다.

6. 정리와 다음 단계

pyenv는 파이썬 버전 관리에 있어 매우 편리하고 강력한 도구입니다. 특히 여러 프로젝트에서 서로 다른 버전의 Python을 사용해야 하는 개발자에게 pyenv를 사용하면 버전 전환이 쉬워지고, 개발 환경을 보다 효율적으로 관리할 수 있습니다. 또한, virtualenv와 결합하면 프로젝트별 의존성 관리도 쉬워지고, 동일한 시스템에서 여러 가상환경을 병행해 사용할 수 있습니다.

pyenv 활용 정리

버전 관리의 간편함: pyenv를 사용하면 시스템 전체 또는 프로젝트별로 여러 Python 버전을 손쉽게 전환할 수 있습니다.
가상환경 병행 사용: pyenv-virtualenv와 virtualenv를 활용하면 Python 프로젝트의 의존성을 분리하고 여러 프로젝트를 효율적으로 관리할 수 있습니다.
문제 해결의 중요성: pyenv를 사용할 때 발생할 수 있는 오류나 충돌에도 대비하여, 올바른 의존성 설정과 버전 지정을 하는 것이 중요합니다.

다음 단계

pyenv로 더 높은 효율을 추구하기: pyenv의 기본 조작을 숙달했다면, 개발 환경을 한층 더 효율화하기 위해 pipenv나 poetry 같은 도구와의 병행 사용도 검토해 보세요. 이러한 도구는 의존성 관리를 더욱 단순화하고, 프로젝트별 셋업을 자동화할 수 있습니다.
다른 개발 환경에도 적용하기: Windows 사용자라면 pyenv가 직접 지원되지 않으므로 WSL(Windows Subsystem for Linux)을 사용하는 방법이나, Anaconda 등 다른 도구를 검토해 보는 것도 좋습니다.
실제 프로젝트에서 시도해 보기: 이론을 이해하는 데 그치지 말고, 실제로 프로젝트에 pyenv를 도입해 보세요. 기존 프로젝트나 새로운 프로젝트에 pyenv를 적용하고 가상환경을 만들면서, 라이브러리 관리가 얼마나 매끄러워지는지 직접 체감해 보시기 바랍니다.

オープンソースの力を活用する方法～Ubuntuの世界へようこそ～

Ubuntuにおけるpyenvのセットアップと活用法｜Python環境管理ガイド

目次 1 1. はじめに1.1 Pythonバージョン管理の重要性1.2 Ubuntuとpyenvの組み合わせの利点2 …