파이썬 프로젝트 우아하게 시작하기: pyenv, poetry

여러분의 맥북에는 이미 파이썬(Python)이 깔려있다. 맥 OS의 여러 유틸리티들이 파이썬을 필요로 하기 때문이다.
그럼 파이썬 프로젝트를 시작할 때, 파이썬을 별도로 설치하지 않아도 되는 것일까?
그렇지 않다. 프로젝트마다 요구하는 파이썬의 버전이 다르기 때문이다.
이 글은 파이썬 프로젝트를 우아하게 시작하려면, 반드시 이용해야 할 버전 관리 도구(version manager)와 의존성 관리 도구(dependency manager)의 필요성과 간단한 사용 방법을 소개한다.

---

파이썬의 버전관리

버전관리의 필요성

프로젝트마다 파이썬 버전을 맞춰야하는 이유가 무엇일까? 무조건 최신의 파이썬을 쓰면 안되는 것일까?

- 파이썬 버전을 올리면 지원하는 기본 라이브러리가 사라지거나, 코드의 기능이 달라질 수 있다. 내 컴퓨터에서는 잘되는 from xxx import xxx 라인이 옆 사람 컴퓨터에서는 안되는 일이 일어날 수 있다. 또 하나 예를 들자면, print("abc" + b"def") 라는 라인은 Python 2 에서는 "abcdef"를 출력하지만, Python 3에서는 Type Error를 반환한다. b"def"는 bytes를 의미한다. 내 코드에는 그럴 문제 없다고 생각하지 몰라도, 내 코드가 의존하는 다른 패키지가 문제가 있을 수 있다.

- 최신의 파이썬 버전에서는 실험적인 기능들을 빠르게 사용할 수 있다. 한편, 이 기능들은 "실험적"인 만큼 보안상의 문제나 기능상의 문제가 있을 수 있다.

- 앞서, 맥 OS 시스템에 기본으로 깔려있는 파이썬이 있다고 했다. 이 파이썬의 버전을 성급히 변경했다가는 맥북의 시스템 유틸리티의 정상적인 동작을 보장할 수 없다.

파이썬 버전 개념

2025년 12월 기준, https://devguide.python.org/versions/

파이썬은 버전마다 5단계의 생애주기를 거쳐 관리된다. 이에 관한 내용은 이 주소에서 확인할 수 있고, 해당 내용의 번역과 첨언을 아래에 적어둔다.
1. feature
- 베타 오픈도 되기 전 단계. 이 단계는 릴리즈(binary)마다 새로운 기능, 오류 수정, 보안 개선 코드 등을 위한 코드 변경이 발생한다.
2. prerelease
- 베타 오픈 단계. 새로운 기능이 추가되지는 않지만 기능의 수정(중요한 변경 사항 포함), 오류 수정, 보안 개선 등을 위한 코드 변경이 발생한다.
3. bugfix
- 버전이 정식으로 출시된 단계. 오류 수정과 보안 개선은 이뤄진다. 새로운 릴리즈(binary)는 약 2달마다 출시되며, 유지(maintenance) 혹은 안정(stable) 단계라고도 불린다.
4. security
- 출시 후 2년이 경과된 단계. 보안 문제만이 반영되며, 더 이상 새로운 릴리즈가 나오지 않는다. 필요에 따라 코드 변경이 있을 수는 있지만 빌드는 사용자가 직접 해야 한다(source-only versions can be realeased as needed).
5. end-of-life
- 출시 후 5년이 경과된 단계. 더 이상의 릴리즈는 없다.

파이썬 버전 매니저: pyenv

Pyenv는 인기있는 Python version manager다. 대안으로는 asdf도 사용해봤다. (이름이 괴상한) asdf는 다양한 프로그래밍 언어와 CLI 툴들의 버전 관리를 한 번에 해준다는 장점이 있다. Pyenv의 사용방법을 아래에 간단히 소개한다. 구체적인 사용방법은 공식 문서를 참고하자.

# brew로 pyenv 설치
brew update && brew install pyenv

# pyenv 업그레이드(pyenv에 원하는 Python 버전이 없을때)
brew upgrade pyenv

# 설치된 python 리스트 확인 및 3.13.0 설치/삭제
pyenv versions
pyenv install 3.13.0
pyenv uninstall 3.13.0

# 기본 python을 3.13.0으로 설정
pyenv global 3.13.0

# (프로젝트 루트 경로에서) 이 프로젝트의 python 버전을 3.13.0으로 설정(.python-version 파일이 생긴다)
pyenv local 3.13.0

---

파이썬 의존성

의존성 관리의 필요성

대부분의 프로젝트는 하위 의존성(dependency)을 갖는다. 자동차를 만드는데 필요한 바퀴를 고무 제련단계부터 하고 있으면, 완성된 자동차가 나오기까지 너무 비효율적이다. 그래서 자동차를 만들 때 바퀴는 시제품을 이용하는 것처럼, 프로젝트들은 미리 만들어진 의존성 패키지를 이용한다. 기본적으로 pip라는 python 기본 패키치 설치 도구를 통해 의존성 패키지를 설치하고, 프로젝트마다 이용할 의존성 목록이 기록되는 requirements.txt 파일을 수동으로 관리해야 한다. 

만약 pyenv를 통해 우리 프로젝트가 python 3.13 을 사용하도록 했다면, 그 프로젝트 경로 내에서 쓰이는 pip는 3.13버전의 pip가 된다. 만약 서로 다른 두 프로젝트가 우연히 같은 버전의 파이썬을 사용한다고 하자. 별다른 관리 도구를 사용하지 않는다면, 두 프로젝트의 의존성들이 같은 pip 하위 경로에 섞이게 된다. 이런 상황을 피하기 위해, 패키지를 pip 하위가 아니라 프로젝트 내에 포함하는 것이 좋다. 패키지마다 가상환경을 갖고 있다고 생각하고, 서로 다른 프로젝트의 패키지들 설치 경로를 격리해야한다. 대표적으로 venv가 표준으로써 해당 기능을 지원한다. 비슷한 이름의 virtualenv는 비표준이다.

제일 편한 방법은 Poetry를 이용하는 것이다. Poetry는 패키지 설치 뿐만 아니라 파이썬 프로젝트의 패키징(배포)까지 관리해주는 도구다. Javascript에 익숙한 사람에게는 npm과 비슷하다(패키지를 관리해준다는 측면에서)고 생각하면 이해가 쉽다. pyproject.toml은 프로젝트의 의존성 관리에 필요한 정보들이 작성되며, poetry가 자동으로 관리해준다. 사람이 직접 이 파일을 수정하지 않아도 된다. Npm의 package.json이 이것과 대응된다. Conda도 Poetry의 대안이 될 수 있지만, GPU 리소스와 data science, deep learning 쪽에 특화되어 있다. 

 

poetry 이용방법

# poetry로 프로젝트 시작
poetry init

# poetry로 프로젝트 실행(poetry가 하위 의존성들을 관리하므로, 반드시 이렇게 실행해야한다!)
poetry run python main.py

# poetry에 의존성 xx 추가/삭제
poetry add xx
poetry remove xx

# pyproject.toml을 참고하여, 필요한 의존성들 모두 설치
poetry install

자세한 내용은 공식 문서를 참고하자.