vscode에서 파이썬 개발환경 세팅하기 (가상환경, 개발도구)

안녕하세요, 이번 포스트에서는 vscode로 파이썬 개발을 시작하기 위해 개발 환경을 구성하는 방법에 대해서 다루어보겠습니다. 파이썬 관리 도구 및 가상환경, 패키지 매니저, 그리고 스타일 및 정적검사를 위한 개발 도구까지 소개해 보도록 하겠습니다. 파이썬으로 프로젝트를 구성하시는 분들에게 많은 도움이 되었으면 합니다.

vscode 설치하기

우선 당연하게도 vscode를 설치해야 합니다. 아래 링크를 통해 본인의 환경에 맞는 vscode를 설치합니다.

https://code.visualstudio.com/download

파이썬 설치

파이썬을 공식 홈페이지를 통해 설치할 수도 있지만, 저희는 pyenv라는 도구를 활용할 계획입니다. pyenv는 파이썬 버전을 쉽게 바꿀 수 있게 도와주는 툴입니다. 프로젝트를 여러 개 진행하다 보면 프로젝트들 간의 파이썬 버전이 달라질 수 있습니다. 이때 pyenv를 활용하면 손쉽게 해당되는 파이썬 버전을 설치하거나 변경할 수 있습니다.

pyenv 설치

Mac 사용자

맥 사용자의 경우에는 brew를 통해서 pyenv를 쉽게 설치할 수 있습니다.

brew update
brew install pyenv

리눅스/WSL 사용자

리눅스 사용자분들은 아래 스크립트를 입력합니다.

curl https://pyenv.run | bash

이후에 아래 스크립트를 통해 ~/.bashrc 혹은 zsh를 사용하고 계시다면 ~/.zshrc에 PYENV를 등록합니다.

For Bash

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

For Zsh

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

윈도우 사용자

윈도우에서는 공식적으로 pyenv가 지원되지 않습니다. 하지만, pyenv-win이라는 깃헙 레포지토리가 운영되고 있습니다. 아래 주소를 참고하여 설치하실 수 있습니다.

https://github.com/pyenv-win/pyenv-win#installation

pyenv 명령어 살펴보기

pyenv를 설치하셨으면 기본적인 명령어들을 살펴보겠습니다.

1. 설치 가능한 파이썬 버전 살펴보기

아래 명령어를 입력하시면 사용 가능한 파이썬 버전을 확인하실 수 있습니다.

pyenv install --list

아래와 같이 다양한 버전들이 나오는데, 기본적으로는 아무것도 붙어있지 않고 숫자만 있는 버전을 사용하시면 됩니다.

2. 파이썬 설치하기

위에서 확인한 버전을 기반으로 원하는 파이썬 버전을 설치할 수 있습니다. pyenv install <설치버전>을 입력해 주시면 됩니다. 예를 들어 3.11.4 버전의 파이썬을 설치하기 위해서는 아래와 같이 입력해 주세요.

pyenv install 3.11.4

3. 설치된 파이썬 버전 확인하기

설치되어 있는 파이썬 버전을 확인하기 위해서는 아래 명령어를 입력합니다.

pyenv versions

4. 글로벌/로컬 파이썬 버전 설정하기

pyenv global <설치 버전>을 입력하시면 해당 파이썬을 터미널의 기본 파이썬 버전으로 설정하실 수 있습니다. 반대로 특정 폴더 내에서만 파이썬 버전을 변경하고 싶으시다면 pyenv local <설치 버전>을 입력합니다.

pyenv global 3.11.4

5. 파이썬 버전 활성화하기

쉘에서 특정 파이썬 버전을 활성화하고 싶으시다면 아래 명령어를 입력합니다.

pyenv shell <설치버전>

vscode 파이썬 익스텐션 설치하기

vscode를 열고 좌측 Extensions에서 Python이라고 검색해 아래의 Python 익스텐션을 설치해 줍니다. 해당 익스텐션은 마이크로소프트에서 관리하고 있으며, 자동완성이나 스타일 검사, 디버깅 등을 도와주는 역할을 합니다. vscode에서 파이썬을 사용한다면 반드시 사용해야 하는 익스텐션입니다.

가상환경 설치

이제 파이썬 가상환경을 설치해야 합니다. 가상환경은 같은 파이썬 버전이라도 다른 라이브러리 환경을 쓸 수 있기 때문에 필요합니다. 예를 들어, 예전에 만들어진 프로젝트와 새롭게 시작하는 프로젝트의 라이브러리 버전이 다르다면, 가상환경을 사용해 두 프로젝트를 서로 격리해서 관리할 수 있습니다.

파이썬에서 가상환경을 만드는 것을 도와주는 도구에는 많은 도구들이 있습니다. 그중에서도 저희가 사용할 것은 poetry라는 도구입니다. poetry는 가상환경을 자동으로 만들어주는 역할 뿐만이 아니라 해당 도구를 통해 라이브러리를 설치한다면 라이브러리들 간의 의존성 관리를 쉽게 도와줍니다. 더욱이 라이브러리를 쉽게 배포할 수 있게 도와주는 역할도 합니다.

poetry를 설치하기 위해서는 아래 명령어를 입력합니다.

맥,리눅스/WSL

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

윈도우 (파워쉘)

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

설치가 완료되었다면 아래 명령어를 입력해 정상적으로 poetry가 설치되었는지 확인합니다.

poetry --version

아래와 같은 이미지가 나타나면 정상적으로 설치가 완료된 것입니다.

Poetry 명령어 살펴보기

1. poetry 최초 활성화

개발하고 있는 프로젝트에서 poetry를 활성화하기 위해서는 아래 명령어를 입력합니다.

poetry init

커맨드 라인의 질문들을 답하고 나면 pyproject.toml 파일이 생깁니다. 여기에는 해당 프로젝트에서 사용할 라이브러리 의존성과 설정들이 들어가게 됩니다.

2. poetry 가상환경 쉘 접속

현재 poetry의 가상환경에 접속하기 위해서는 poetry shell 명령어를 입력합니다.

poetry shell

3. 라이브러리 설치(추가)

라이브러리를 설치하기 위해서는 poetry add 명령어를 입력해 주시면 됩니다. 해당 명령어를 통해 라이브러리를 설치하면 해당 라이브러리가 pyproject.toml에 등록되고, poetry.lock파일이 생성 및 업데이트됩니다. 앞으로, 모든 라이브러리는 해당 명령어로 추가해주어야 합니다. (pip install로 설치하게 되면 poetry에 의해 의존성관리가 되지 않습니다.)

poetry add <라이브러리 이름>

4. 개발환경 라이브러리 설치(추가)

개발 환경에서만 사용하는 라이브러리를 설치하기 위해서는 아래 명령어를 입력합니다.

poetry add --group dev <라이브러리 이름>

5. 라이브러리 제거

peotry remove

6. 라이브러리 동기화

pyproject.toml과 poetry.lock파일이 있다면 다른 환경에서도 쉽게 모든 라이브러리를 동기화할 수 있습니다. 일일이 라이브러리를 처음부터 추가할 필요 없이 poetry install 명령어를 입력하면 됩니다.

poetry install

vscode에서 가상환경 활성화하기

위에서 만든 가상환경을 vscode에 등록해 주면 쉘을 열 때마다 poetry shell을 입력할 필요가 없습니다. 또한, 해당 가상환경에 설치된 의존성들을 기반으로 vscode에서 정적검사 수행 및 자동완성을 도와줍니다.

1. 아래 명령어를 입력해 가상환경 경로를 확인하고 복사합니다.

poetry env info

2. cmd(ctrl) + shift + p를 입력하여 명령어 팔레트를 열고, Python: Select Interpreter를 입력합니다.
3. 목록에 원하는 가상환경이 있다면 해당 가상환경을 선택하면 되고, 그렇지 않다면 Enter interpreter path를 선택합니다.
4. 1번에서 복사한 경로를 붙여 넣고 엔터 버튼을 누릅니다.

이제 vscode에서 선택한 가상환경을 기반으로 정적 검사 및 자동완성을 지원할 수 있게 되었을 겁니다. 쉘을 종료했다가 다시 열어서 가상환경이 활성화 되는지 확인합니다. (쉘을 여신후에 2초정도 대기해주셔야 합니다.)

개발 도구 설치하기

이번에는 개발을 도와주는 도구들을 설치해 보겠습니다. 개발과정에서 코드 스타일을 맞추거나 정적 타입 검사 등을 도와주는 툴들입니다. 이러한 부분을 해당 툴들로 자동화시킨다면 코드 포맷팅과 관련된 이슈를 줄일 수 있습니다.

1. ruff

파이썬에서는 PEP8이라는 스타일 가이드를 제시하고 있습니다. ruff는 해당 스타일 가이드에 맞지 않은 코드에 대해서 경고를 주거나 코드 변환을 해주는 도구입니다. Rust로 만들어져있어서 비슷한 다른 툴(pylint, flake8)등 보다 월등히 (100~200x) 빠르며, 자동 코드 변환까지 지원하기 때문에 다른 툴 (black, isort 등)을 설치하지 않아도 됩니다.

우선, 아래 명령어를 입력하여 ruff를 설치합니다.

poetry add --group dev ruff

만약 포맷팅 스타일의 설정을 변경하고 싶으시다면 여기를 참고해서 pyproject.toml 파일을 수정합니다.

vscode에서 ruff를 활용하기 위해서는 익스텐션을 설치해 주셔야 합니다. vscode 좌측의 Extensions에서 ruff를 검색하셔서 아래 익스텐션을 설치합니다.

2. mypy

다음으로는 정적 타입 검사 도구 mypy를 설치할 차례입니다. 파이썬은 3.5이후부터 타입 힌트라는 기능을 제공하고 있는데, 이를 mypy와 같은 정적 검사 도구와 함께 활용하게 되면 개발 환경에서 타입 오류를 미리 잡을 수 있습니다.

아래 명령어를 통해 mypy를 설치할 수 있습니다.

poetry add --group dev mypy

mypy 역시 pyproject.toml에서 설정을 변경할 수 있습니다. 세부적인 설정을 원하시는 분들은 여기를 참고해서 pyproject.toml 파일을 수정할 수 있습니다.

vscode에서 mypy를 활용하기 위해서는 익스텐션을 설치해야합니다.

vscode settings 설정

위에서 설정한 도구들이 잘 작동하기 위해서 vscode에 몇 가지 설정을 해주어야 합니다. 프로젝트 최상위 경로에 .vscode 경로를 만들고 이 안에 settings.json파일을 만들고, 아래와 같이 입력합니다.

{
  "editor.formatOnSave": true,
  "python.analysis.typeCheckingMode": "off",
  "ruff.importStrategy": "fromEnvironment",
  "mypy-type-checker.importStrategy": "fromEnvironment"
}

• "editor.formatOnSave": true는 저장 시에 포맷팅(자동수정)을 하겠다는 설정입니다.
• "python.analysis.typeCheckingMode": "off"는 mypy를 사용하기 위해서 파이썬 익스텐션에서 기본적으로 사용하는 타입 검사를 끄겠다는 의미입니다. mypy가 아니라 pyright를 타입 검사 도구로 사용하시면 해당 부분을 basic 혹은 strict로 설정하시면 됩니다.
• "ruff.importStrategy": "fromEnvironment","mypy-type-checker.importStrategy": "fromEnvironment"`는 vscode의 ruff와 mypy 익스텐션이 가상환경에 설치되어 있는 버전의 ruff와 mypy를 쓰겠다는 옵션입니다.

마무리

이제 파이썬을 활용한 개발 준비가 끝났습니다. 넓은 범위를 다루려다 보니 상세히 작성하지 못한 부분이 있습니다. 만약 위의 과정을 따라서 개발 환경을 구성하시다가 어려운 부분이나 막히는 부분이 있으시다면 댓글로 질문을 남겨주시면 글 내용을 보충하거나, 답변으로 이를 보완할 수 있도록 하겠습니다. 긴 글 읽어주셔서 감사합니다.

참고자료

• pyenv github repository
• Poetry
• Ruff
• Mypy