도구 Python과 프로젝트 Python

Poetry를 실행하는 Python과 프로젝트 코드를 실행하는 Python은 별도입니다. 현재 Poetry 도구의 Python 3.10 이상 조건만 보고 프로젝트도 무조건 같은 버전이어야 한다고 생각하지 않습니다. 프로젝트 pyproject의 지원 범위를 확인합니다.

공식 환경 문서는 이미 가상환경 안에서 실행 중이면 그 환경을 사용할 수 있다고 설명합니다. 예상과 다른 환경을 재사용할 수 있으므로 현재 터미널의 활성화 상태부터 기록합니다. 에디터 인터프리터 설정도 별도로 확인합니다.

현재 환경 경로 읽기

프로젝트 폴더에서 다음 명령의 출력을 비교합니다. 조회 목적의 예시이며 이 글에서 실제 Poetry 환경을 만든 결과는 아닙니다.

poetry env info
poetry env info --path
poetry run python -c "import sys; print(sys.executable); print(sys.version)"

환경 경로와 실행 파일·버전이 의도한 프로젝트인지 확인합니다. 폴더 이름만 비슷한 다른 프로젝트 환경을 골라 놓지 않았는지 봅니다. 일반 python의 출력과 다르다면 패키지 위치가 다른 이유가 될 수 있습니다.

사용할 Python 명시

공식 문서의 poetry env use /full/path/to/python처럼 원하는 인터프리터의 전체 경로를 지정할 수 있습니다. Windows도 실제 설치된 python.exe 경로를 사용하고 공백이 있는 경로는 셸에 맞게 인용합니다. 예시 경로를 그대로 붙여 넣지 않습니다.

선택할 Python은 프로젝트 지원 범위를 만족해야 합니다. PATH에 이름이 있다는 것과 지원 버전이라는 것은 별도입니다. 선택 뒤 환경 정보·설치·실행 출력을 다시 확인합니다. 먼저 Python 설치 여부를 확인하지 않고 환경 선택 명령이 새 인터프리터를 내려받는다고 설명하지 않습니다.

activate와 shell 차이

poetry env activate는 활성화할 명령을 출력합니다. 명령을 입력한 사실만으로 현재 셸이 이미 활성화됐다고 판단하지 않습니다. 출력된 명령을 현재 셸 문법에 맞게 적용하거나, 활성화 없이 poetry run으로 실행합니다.

poetry shell은 현재 별도 poetry-plugin-shell로 이동했습니다. 기본 설치에서 명령이 없다고 프로젝트 환경이 깨졌다고 보지 않습니다. 단순 실행 확인은 플러그인 설치 없이 poetry run으로 할 수 있습니다.

모듈 없음의 자체 진단 사례

가상의 전역 환경 A에 패키지가 있고 Poetry 환경 B에는 없다고 해 보겠습니다. 이 경우 B에서 모듈 없음이 나오는 것은 자연스럽습니다. 프로젝트 요구 조건에 패키지를 선언하고 B에 설치할지 판단해야 하며, 전역 설치가 성공했다는 로그를 B의 설치 근거로 쓰지 않습니다.

환경 삭제·캐시 정리 전에는 경로와 필요한 파일을 확인합니다. 이 글은 공식 환경 동작과 자체 A/B 사례를 검토했으며 실제 환경 전환·패키지 설치·환경 삭제·에디터 설정 변경은 실행하지 않았습니다.

목적별 가이드

하려는 일 가이드
프로젝트·잠금 파일 관리부터 시작 Poetry 첫 사용
uv의 프로젝트 흐름 확인 uv

참고 자료