[python] pyenv + uv 설치와 사용법(linux, macos)

1. pyenv 설치

# Linux (Ubuntu) 환경
$ sudo apt update
$ sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev git

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

# 또는 curl 로 간단하게 설치
$ curl https://pyenv.run | bash


# macos 환경
% brew install pyenv

아무래도 업데이트가 된 모양이다.

2. 프로필 파일 수정

2-1. 로그인 셸

# zsh
% vi ~/.zprofile

# bash
$ vi ~/.bash_profile

# 맨 아래에 추가
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"

# 수정 후
# zsh
% source ~/.zprofile

# bash
$ source ~/.bash_profile

2-2. 인터랙티브 셸

# zsh
% vi ~/.zshrc

# bash
$ vi ~/.bashrc

# 맨 아래에 추가...
eval "$(pyenv init -)"

# 수정 후
# zsh
% source ~/.zshrc

# bash
$ source ~/.bashrc

3. pyenv 로 다른 파이썬 버전 설치

% pyenv install 3.12.1

설치가 다 되었다.

4. python 버전 확인

내 PC에는 3개가 딸려있다.

% pyenv versions

지금 버전은 3.11.9 이다.(uvtest)

% python

5 . 폴더 생성 후 다른 버전 설정

% mkdir python3.10.13
% cd python3.10.13
% pyenv local 3.10.13

이렇게 .python-version 파일이 생긴다.

버전이 방금 설정했던 3.10.13 이다.

python 을 찍어보면 3.10.13 이라고 나온다.

6. uv 란?

uv는 Rust로 작성된 고속 의존성 해석 엔진을 앞세워, 가상환경 생성, 의존성 관리, 파이썬 버전 관리, 패키징, 포매터/린터 같은 서드파티 도구 실행을 한번에 잘? 처리해준다.

7. 설치해보자.

7-1. 명령어

# 리눅스, macos 겸용
% curl -LsSf https://astral.sh/uv/install.sh | sh

# 또는 macos 전용
# brew install uv

7-2. 설치결과

8. uv 로 가상환경 설정

최종적으로는 가상환경을 설정하면 이런식으로 (환경명칭) 이 붙게 된다.

8-1. 프로필 파일 수정

uv 경로 PATH에 등록
맨 아래에 다음 코드를 넣는다.

# zsh
% vi ~/.zshrc

# bash
$ vi ~/.bashrc

# 맨 아래에 추가
PATH="$HOME/.local/bin:$PATH"

# 수정 후
# zsh
% source ~/.zshrc

# basg
$ source ~/.bashrc

8-2. venv 설정

% uv venv

3.10.13 으로 가상 환경이 맞춰졌다.

9. 가상환경 버전 바꾸기

9-1. 파이썬 다른 버전 설치

% pyenv install 3.13.3

9-2. 다른 환경으로 사용될 폴더 설정 (3.13.3)

% mkdir python3.13.3
% cd python3.13.3
% pyenv local 3.13.3

9-3. 파이썬 버전 확인

% python

9-4. venv 환경 설정

3.13.3 으로 설정 되었다.

uv venv

9-5. PATH 에 uv 추가

% vi .venv/bin/activate

# 맨 밑에 추가
PATH="$HOME/.local/bin:$PATH"

9-6. activate 프로파일 적용

% source .venv/bin/activate

10. 사용해 보자.

10-1. transformer 설치로 버전 확인

3.10.13 버전

3.13.3 버전
numpy 의 버전이 2.2.6 에서 2.3.0이 되었다.

11. 그냥 귀찮다

11-1. activate 자동 삽입

# .venv/bin/activate 파일에 PATH 설정 추가 (중복 방지)
ACTIVATE_FILE=".venv/bin/activate"
LINE_TO_ADD='PATH="$HOME/.local/bin:$PATH"'

if [ -f "$ACTIVATE_FILE" ]; then
  if ! grep -Fxq "$LINE_TO_ADD" "$ACTIVATE_FILE"; then
    echo "$LINE_TO_ADD" >> "$ACTIVATE_FILE"
    echo "$ACTIVATE_FILE 에 PATH 설정을 추가했습니다."
  else
    echo "$ACTIVATE_FILE 에 PATH 설정이 이미 존재합니다. 변경하지 않았습니다."
  fi
else
  echo "$ACTIVATE_FILE 파일이 존재하지 않습니다."
fi

11-2. 쉘 프로파일에 자동 삽입

bash는 ~/.bashrc
zsh는 ~/.zsh

# ~/.bashrc에 pyenv/uv 설정이 이미 있는지 확인하고 없으면 추가
BASHRC="$HOME/.bashrc"

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

# BLOCK의 첫 줄을 기준으로 이미 있는지 검사
if ! grep -Fxq 'export PATH="$HOME/.local/bin:$PATH"' "$BASHRC"; then
  echo -e "\n# pyenv/uv 설정 추가 시작" >> "$BASHRC"
  echo "$BLOCK" >> "$BASHRC"
  echo "# pyenv/uv 설정 추가 끝" >> "$BASHRC"
  echo "~/.bashrc에 pyenv/uv 설정을 추가했습니다."
else
  echo "~/.bashrc에 pyenv/uv 설정이 이미 존재합니다. 변경하지 않았습니다."
fi

Finally

허깅페이스의 모델이 만들어진 시기가 달라서 파이썬 최신버전을 사용하기가 어려웠을 때 이런 식으로 극복 가능했다. 그냥 패키지관리는 pyenv와 uv만으로 사용하자. 너무 편하다.