requirements.txt vs pyproject.toml: 패키지 관리 트렌드 변화

요즘 파이썬 프로젝트 하면서 느낀 건데, 의존성 관리가 정말 중요하더라고요. 처음엔 requirements.txt만 쓰다가 나중에 삽질 좀 했거든요. 그래서 pyproject.toml로 갈아탄 경험을 바탕으로 얘기 좀 해볼게요. 두 방식의 차이점이 뭔지, 그리고 뭘 써야 할지 고민하는 분들께 도움이 될 거예요.

일단 requirements.txt는 옛날 방식이라고 생각하면 돼요. 필요한 패키지 이름과 버전을 간단하게 적어놓는 텍스트 파일이죠. pip freeze > requirements.txt 명령어로 슥 만들고, pip install -r requirements.txt로 슥 설치하면 끝! 간단하고 직관적이라 처음엔 좋았는데… 문제는 버전 관리가 좀 빡세다는 거죠. 예를 들어, requests==2.28.1 이렇게 딱 특정 버전만 지정할 수 있다는 점이죠. 좀 더 유연하게 버전 범위를 지정하고 싶을 때는 힘들어요. 그리고 메타데이터 같은 부가 정보도 못 넣으니까요. 작은 프로젝트에는 괜찮지만, 규모가 커지면 관리가 힘들어져요. 제가 처음에 겪었던 쓴맛이죠. 의존성 충돌 때문에 밤새 씨름한 기억이 아직도 생생해요…

반면 pyproject.toml은 좀 더 진화된 방식이에요. PEP 621이라는 파이썬 표준에 맞춰서 프로젝트 정보, 의존성, 빌드 설정 등을 모두 한 파일에 관리하는 거죠. poetry나 pip-tools 같은 도구를 쓰면 더 편리하게 관리할 수 있어요. 이게 뭘까요? 쉽게 말해, 프로젝트 관리 도우미 같은 거라고 생각하면 돼요. 버전도 requests = "^2.28.1" 이런 식으로 범위를 지정할 수 있고, 개발용 패키지(dev-dependencies)도 따로 관리할 수 있어서 정말 편해요. 마치 잘 정돈된 서랍장에 필요한 도구들이 가지런히 정리된 느낌이랄까요?

코드 예시를 보여드릴게요. requirements.txt는 이렇게 간단하죠.

requests==2.28.1
numpy>=1.20
pandas==1.5.0

근데 pyproject.toml (Poetry 사용)은 이렇게 훨씬 자세하죠.

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.1"
numpy = "^1.20"
pandas = "^1.5.0"

[tool.poetry.dev-dependencies]
pytest = "^7.0"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

보시다시피, 개발에 필요한 pytest도 따로 관리할 수 있고, 버전 범위 지정도 가능하죠. 훨씬 체계적이죠?

pyproject.toml을 쓰려면 poetry 같은 도구를 배워야 한다는 게 약간의 진입 장벽이긴 해요. 처음엔 좀 낯설 수 있지만, 익숙해지면 정말 편리하다는 걸 알게 될 거예요. 그리고 pyproject.toml은 PEP 621 표준을 잘 지켜서 작성해야 해요. 그렇지 않으면 빌드 에러가 날 수 있으니까 주의해야 하고요. 팀 프로젝트라면, 모두 같은 방식을 쓰는 게 중요해요. 아니면 혼란이 생기겠죠?

결론적으로, 새로운 프로젝트라면 pyproject.toml과 poetry (혹은 pip-tools)를 강력 추천해요. 처음 설정이 조금 귀찮을 수 있지만, 장기적으로 봤을 때 시간과 노력을 훨씬 절약할 수 있어요. 특히 큰 프로젝트라면 더더욱 그렇고요. requirements.txt는 이미 작은 프로젝트가 있고, 굳이 바꿀 필요가 없다면 유지해도 괜찮아요. 하지만 새로운 프로젝트를 시작한다면 망설이지 말고 pyproject.toml로 시작하세요! 후회하지 않을 거예요. 저처럼 밤새 삽질하는 일은 없을 거예요!