Home
home
🏡 홈
home

Ubuntu 22.04 pyenv 설치 및 활용 가이드

분류
개발지식
태그
Server
Linux
작성자
작성일
2025/10/10 01:06

개요

pyenv는 여러 버전의 Python을 시스템 환경에 간섭하지 않고 독립적으로 설치하고 전환할 수 있게 해주는 도구입니다.
프로젝트마다 다른 Python 버전을 사용해야 하는 경우나, 특정 버전 호환성이 중요한 환경에서 특히 유용합니다.
이 글에서는 Ubuntu 22.04 (Jammy Jellyfish) 기준으로 pyenv 설치부터 기본적인 사용법까지 단계별로 정리하겠습니다.

목차

1.
사전 준비
2.
의존 패키지 설치
3.
pyenv 설치
4.
쉘 설정
5.
Python 버전 설치 및 전환
6.
자주 발생하는 오류 및 해결 방법
7.
마무리 및 참고 자료

1. 사전 준비

Ubuntu 22.04 환경이 준비되어 있어야 합니다.
sudo 권한을 가진 사용자 계정으로 진행하는 것을 권장합니다.
과거에 Python을 수동 설치하거나, 다른 버전 관리 툴(예: conda, asdf)을 사용한 적이 있다면 충돌 가능성을 미리 확인해 주시기 바랍니다.

2. 의존 패키지 설치

pyenv는 Python을 직접 컴파일하여 설치하기 때문에, 필요한 빌드 도구와 라이브러리를 먼저 설치해야 합니다.
다음 명령어를 실행하여 의존 패키지를 설치합니다.
sudo apt update sudo apt install -y \ build-essential \ curl \ libssl-dev \ zlib1g-dev \ libbz2-dev \ libreadline-dev \ libsqlite3-dev \ wget \ llvm \ libncurses5-dev \ libncursesw5-dev \ xz-utils \ tk-dev \ libffi-dev \ liblzma-dev \ python3-openssl \ git
Bash
복사
build-essential은 컴파일에 필요한 기본 도구이며, 나머지는 Python 빌드 시 필요한 필수 라이브러리들입니다.

3. pyenv 설치

이제 pyenv를 설치하겠습니다. 공식 GitHub 저장소에서 직접 클론하여 설치할 수 있습니다.
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
Bash
복사
기본적으로 홈 디렉토리(~/.pyenv)에 설치되며, 원하신다면 다른 경로로 지정하셔도 됩니다.
다만 이후 단계에서 해당 경로를 환경 변수에 맞춰 설정해야 합니다.

4. 쉘 설정

설치한 pyenv가 터미널에서 동작하도록 환경 변수를 등록해야 합니다.
사용 중인 셸에 따라 아래 파일 중 하나를 수정하시면 됩니다.
bash: ~/.bashrc
zsh: ~/.zshrc
fish 또는 기타 셸은 해당 셸의 설정 파일
다음 내용을 파일의 마지막 부분에 추가해 주세요.
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" if command -v pyenv 1>/dev/null 2>&1; then eval "$(pyenv init --path)" eval "$(pyenv init -)" fi
Bash
복사
pyenv init --path는 로그인 셸용, pyenv init -는 인터랙티브 셸용 초기화 명령어입니다.
~/.profile 또는 ~/.bash_profile을 사용 중인 경우, PYENV_ROOT 환경 변수 설정을 그쪽에도 추가하는 것이 좋습니다.
설정을 마쳤다면, 다음 명령어로 적용합니다.
source ~/.bashrc # 또는 source ~/.zshrc
Bash
복사
이제 아래 명령어를 입력하여 pyenv 버전이 출력된다면 정상적으로 설치된 것입니다.
pyenv --version
Bash
복사

5. Python 버전 설치 및 전환

설치 가능한 버전 확인

다음 명령어로 설치 가능한 Python 버전 목록을 확인할 수 있습니다.
pyenv install --list
Bash
복사

원하는 버전 설치

예를 들어, Python 3.11.4를 설치하려면 아래와 같이 입력합니다.
pyenv install 3.11.4
Bash
복사
설치가 완료되면 다음 명령어로 확인합니다.
pyenv versions
Bash
복사

전역 기본 버전 설정

시스템 전체에서 사용할 기본 Python 버전을 지정하려면 다음 명령어를 실행합니다.
pyenv global 3.11.4
Bash
복사
이제 python --version 또는 python3 --version을 입력하면 설정한 버전이 표시됩니다.

프로젝트별 버전 설정

특정 프로젝트 디렉터리에서만 사용할 Python 버전을 지정할 수도 있습니다.
cd my_project pyenv local 3.10.9
Bash
복사
이 명령어를 실행하면 해당 디렉터리와 하위 폴더에서는 자동으로 지정된 Python 버전이 사용됩니다.

6. 자주 발생하는 오류 및 해결 방법

오류 메시지 또는 증상
원인
해결 방법
command not found: pyenv
PATH 설정 누락 또는 초기화 코드 미적용
.bashrc 또는 .zshrc 설정 확인 후 source 명령어로 재적용
Python 설치 실패 (컴파일 오류 등)
필요한 라이브러리 누락
2단계의 의존 패키지 목록을 다시 설치한 후 재시도
zlib module not available
zlib 개발 패키지 누락
sudo apt install zlib1g-dev 후 다시 설치
특정 셸에서만 pyenv가 동작하지 않음
login/non-login 셸 설정 불일치
pyenv init --path.profile에도 추가
오류가 발생했을 때는 터미널 메시지를 잘 확인하시고, 메시지의 키워드로 검색하면 대부분 해결 방법을 쉽게 찾을 수 있습니다.

7. 마무리 및 참고 자료

이제 Ubuntu 22.04 환경에서 pyenv를 이용해 Python 버전을 자유롭게 설치하고 관리할 수 있습니다.
여러 프로젝트에서 다양한 Python 버전을 사용하는 개발 환경을 구성할 때 매우 유용합니다.
또한, 다음과 같은 플러그인을 추가로 설치하면 더 강력하게 활용할 수 있습니다.
pyenv-virtualenv: 가상환경 관리 기능 추가
pyenv-update: pyenv 자체 업데이트 관리

참고 링크