pycharm, poetry, 가상환경

너무나 쉽지만,
항상 까먹는 PyCharm에서 poetry를 사용해 가상환경(.venv)을 설치하고 연동하는 방법을 처음부터 끝까지 자세히 알아보자.

⭕️ poetry를 사용하면 좋은 점
poetry는 Python 패키지 관리와 가상환경 관리를 도와주는 도구인데,
한마디로 정리하면 "pip + virtualenv + setuptools를 한 방에 해결해주는 깔끔한 툴"이다.

✅ 1. Poetry 설치

먼저, 터미널에서 Poetry가 설치되어 있는지 확인한다.

poetry version

없으면 아랭 명령어로 설치한다.

curl -sSL https://install.python-poetry.org | python3 -

✅ 2. PyCharm 프로젝트 폴더 준비

PyCharm에서 프로젝트 폴더를 열거나 새 프로젝트를 생성한다.

✅ 3. Poetry 초기화

터미널(프로젝트 루트 경로)에서 아래 명령어를 실행한다:

poetry init

질문에 따라 프로젝트 이름, 버전 등을 입력하거나 그냥 엔터로 넘겨도 된다.
pyproject.toml 파일이 생성된다.

✅ 4. 가상환경(.venv) 생성

Poetry는 프로젝트별 가상환경을 자동으로 생성한다.
먼저 Python 버전으로 가상환경을 지정한 후,

poetry env use python3.x

Poetry는 .venv 폴더를 프로젝트 디렉토리 내부에 두지 않고,
기본적으로 ~/.cache/pypoetry/virtualenvs/에 가상환경을 만든다.

(선택) 로컬 프로젝트 안에 .venv로 생성하고 싶으면 아래 설정을 한다.

poetry config virtualenvs.in-project true

.venv 폴더가 생성된다.

poetry install

✅ 5. PyCharm에 Poetry 가상환경 연결

1. PyCharm에서 File > Settings > Python Interpreter (Mac: PyCharm > Preferences > Python Interpreter)

2. 오른쪽 상단의 톱니바퀴 아이콘 클릭 → Add Interpreter

3. Add Local Interpreter → Existing environment 선택

4. ... 버튼을 눌러 가상환경 경로를 찾아 선택

   프로젝트 안에 .venv가 있다면:

   <프로젝트 경로>/.venv/bin/python
   

   시스템 경로에 있다면 poetry env info --path로 위치를 확인:

   poetry env info --path
   

   출력 경로의 bin/python 선택.

5. OK → 적용.

✅ 6. Poetry 의존성 추가 방법

poetry add package_name

자동으로 pyproject.toml과 poetry.lock이 업데이트된다. PyCharm에서도 바로 반영된다.

🍀 터미널에서 가상환경 활성화

가상환경의 경로가 /Users/xxx/python/project-name/.venv 같은 형태라면,

source .venv/bin/activate