pyproject.toml 단독으로 사용해도 될까?

Python 프로젝트에서 Poetry를 사용할 때, 가장 많이 등장하는 두 파일은 바로

• pyproject.toml
• poetry.lock입니다.

이때 흔히 드는 의문 하나:

“pyproject.toml만 있어도 프로젝트 실행 가능한가요?”

 

가능은 하지만, 안전하지는 않습니다

pyproject.toml은 필요한 패키지를 선언하는 파일입니다.
예를 들어:

[tool.poetry.dependencies]
pandas = "^2.0.0"

이런 식으로 원하는 패키지를 적어두면, Poetry는 해당 조건에 맞는 최신 버전을 설치합니다.

 

그런데 왜 문제가 될까?

문제는 다음과 같습니다:

• 팀원마다 설치되는 버전이 다를 수 있음
• 서버나 CI/CD 환경에서 예상치 못한 충돌 발생 가능
• 종속 패키지 간 버전 충돌 발생 위험 증가

 

pyproject.toml의 역할은?

 

• 이 파일은 "나는 이런 패키지가 필요해!"라는 **요구사항(requirements)**을 기술합니다.
• 하지만 여기에만 의존할 경우, Poetry는 최신 호환 가능한 버전을 설치하게 됩니다.
  • → 팀원/서버마다 설치되는 버전이 다를 수 있음
  • → 예측 불가한 동작이 생길 수 있음

 

그래서 poetry.lock이 필요한 이유

poetry.lock은 실제로 설치된 정확한 패키지 버전과 종속성 트리를 저장하는 파일입니다.

이 파일이 있으면:

• 모든 개발자와 서버에서 완전히 동일한 환경 구성 가능
• 충돌 없는, 검증된 패키지 조합 유지
• 배포 환경에서도 신뢰성 확보

 

결론

 

🎯 작업의 재현성과 안정성이 중요하다면
꼭 poetry.lock을 함께 사용하세요!