프로젝트마다 다른 파이썬 가상환경, VSCode 가상환경 인터프리터 자동 전환 설정

VSCode 가상환경 인터프리터 자동 전환 설정 방법을 찾고 있다면, 바로 내 이야기가 떠오를 것이다. 새 프로젝트 폴더를 열 때마다 해당 프로젝트에 맞는 파이썬 가상환경을 만들었지만, VSCode가 이전에 선택한 인터프리터를 그대로 유지해 실행할 때마다 모듈을 찾지 못한다는 오류가 반복된다.

이러한 현상의 근본 원인은 VSCode가 기본적으로 워크스페이스 전체에 하나의 인터프리터를 저장하고, 폴더를 전환해도 자동으로 재탐색하지 않기 때문이다. 특히 .venv 폴더를 프로젝트 루트에 두었음에도 settings.json에 명시되지 않으면 자동 전환이 일어나지 않는다.

해결책은 프로젝트별 설정 파일에 인터프리터 경로를 명시하고, VSCode가 폴더를 열 때마다 해당 파일을 읽어 자동으로 전환하도록 구성하는 것이다. 이 글에서는 공식 문서와 실무 사례를 기반으로 단계별 설정 방법을 상세히 제시한다.

VSCode 가상환경 인터프리터 자동 전환 설정 방법 개요

VSCode 1.85.2 버전부터 파이썬 확장은 python.defaultInterpreterPath와 python.venvPath 두 가지 설정을 지원한다. 첫 번째는 전역 기본 인터프리터를 지정하고, 두 번째는 프로젝트 루트 아래에 있는 가상환경 폴더를 자동 탐색한다. 이 두 옵션을 적절히 조합하면 새 폴더를 열 때마다 인터프리터가 자동으로 전환된다.

예를 들어, 프로젝트 A가 Python 3.11.4 로 만든 가상환경 .venv에 의존하고, 프로젝트 B는 3.10.12 로 만든 env 폴더를 사용한다면, 각각의 .vscode/settings.json에 다음과 같이 명시한다.

{
    "python.defaultInterpreterPath": "",
    "python.venvPath": ".venv"
}

이때 python.defaultInterpreterPath를 빈 문자열로 두면 VSCode가 폴더 내 .venv 혹은 env를 자동 탐색한다. 공식 문서에서는 이 방식을 “프로젝트 수준 자동 전환”이라고 권장한다. VSCode Python Environments에서 자세히 확인할 수 있다.

Photo by Christina Morillo on Pexels

워크스페이스 설정 파일(.vscode/settings.json) 활용

워크스페이스 설정 파일은 프로젝트 루트에 .vscode 폴더를 만들고 그 안에 settings.json을 배치한다. 여기에는 인터프리터 경로뿐 아니라 자동 완성, 린터, 포맷터 옵션도 함께 정의할 수 있다. 아래 표는 전역 설정 vs. 폴더별 설정의 차이를 한눈에 보여준다.

표에서 알 수 있듯이 폴더별 설정이 전역 설정보다 우선 적용된다. 따라서 프로젝트마다 다른 파이썬 버전을 사용할 때는 반드시 .vscode/settings.json에 python.venvPath를 지정해야 한다. Windows 환경에서 전역 가상환경 디렉터리를 쓰고 싶다면 절대 경로를 명시한다.

설정 파일을 저장한 뒤 VSCode를 재시작하거나 Ctrl+Shift+P → Reload Window 명령을 실행하면 즉시 적용된다.

폴더별 .pythonPath 설정과 최신 권장 방식

VSCode 1.80 이전 버전에서는 python.pythonPath 옵션을 사용했지만, 1.80 이후부터는 이 옵션이 폐기되고 python.defaultInterpreterPath와 python.venvPath가 공식 대체 옵션으로 자리 잡았다. 기존 프로젝트를 최신 방식으로 마이그레이션하려면 다음 절차를 따른다.

이 과정을 마치면 VSCode는 폴더를 열 때마다 자동으로 해당 가상환경을 선택한다.

명령 팔레트와 자동 전환 스크립트 적용

자동 전환을 수동으로 트리거하고 싶을 때는 명령 팔레트에 Python: Select Interpreter 를 입력하거나, 아래와 같은 간단한 tasks.json 스크립트를 활용한다.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Activate Python venv",
            "type": "shell",
            "command": "${workspaceFolder}/.venv/Scripts/activate",
            "problemMatcher": []
        }
    ]
}

위 작업을 실행하면 터미널이 자동으로 가상환경을 활성화한다. 이후 Ctrl+Shift+P → Python: Refresh Interpreter List 를 누르면 새 인터프리터가 즉시 반영된다.

흔히 하는 실수

• 가상환경 폴더명을 틀리게 지정 – VSCode는 .venv, env, venv 등 기본 이름만 자동 탐색한다. 다른 이름을 썼다면 python.venvPath에 정확히 적어야 한다.
• 전역 settings.json에만 설정 – 전역 설정은 폴더별 설정보다 우선순위가 낮아, 프로젝트마다 다른 환경을 쓸 경우 무시된다.
• 인터프리터 경로에 역슬래시(\) 사용 – Windows에서는 역슬래시 대신 슬래시(/) 혹은 이스케이프된 두 개(\\)를 써야 JSON 파싱 오류가 발생하지 않는다.
• 가상환경이 아직 생성되지 않은 상태에서 설정만 넣음 – VSCode는 존재하는 폴더만 인식한다. python -m venv .venv 로 먼저 환경을 만든 뒤 설정을 적용한다.
• 다중 루트 워크스페이스에서 설정 충돌 – 여러 폴더를 하나의 워크스페이스에 추가했을 때는 각각의 .vscode/settings.json이 독립적으로 작동한다. 루트 레벨에 settings.json을 두면 하위 폴더 설정을 덮어쓸 수 있다.

한 단계 더 — 고급 팁

1. 동적 python.venvPath 변수 사용 – VSCode 1.87부터는 환경 변수를 지원한다. 예를 들어 "python.venvPath": "${workspaceFolder}/.venv" 로 지정하면 워크스페이스가 이동해도 경로가 자동 보정된다.
2. 프로젝트 별 pyproject.toml 연동 – poetry 혹은 pipenv 로 관리되는 프로젝트라면 python.defaultInterpreterPath 대신 python.envFile에 .env 파일을 지정해 VIRTUAL_ENV 변수를 로드한다.
3. 리모트 컨테이너와 DevContainer 활용 – Docker 기반 개발 환경에서는 .devcontainer/devcontainer.json 안에 "settings": {"python.venvPath": "/workspace/.venv"} 를 넣어 컨테이너가 시작될 때 자동 전환한다.
4. 다중 인터프리터 테스트 자동화 – pytest 를 실행할 때 PYTHONPATH 를 명시하고 tox 로 여러 파이썬 버전을 동시에 검증하면, VSCode 설정이 올바른지 CI 단계에서 검증할 수 있다.

실제 프로젝트 적용 사례와 주의사항

다음은 3개의 서로 다른 파이썬 버전을 사용하는 마이크로서비스 프로젝트를 VSCode에 적용한 실제 예시다.

.
├─ service-a/
│  └─ .vscode/
│     └─ settings.json   // python.venvPath: ".venv-a"
│  └─ .venv-a/
│  └─ requirements.txt
├─ service-b/
│  └─ .vscode/
│     └─ settings.json   // python.venvPath: ".venv-b"
│  └─ .venv-b/
│  └─ requirements.txt
└─ common/
   └─ .vscode/
      └─ settings.json   // python.defaultInterpreterPath: "C:/Python311/python.exe"

각 서비스 폴더에 독립적인 .vscode/settings.json을 두었기 때문에 VSCode는 service-a를 열면 .venv-a, service-b를 열면 .venv-b를 자동 선택한다. common 폴더는 전역 파이썬 3.11을 사용하도록 지정해, 공유 스크립트가 동일 버전에서 실행되도록 보장한다.

※ 주의 – 위 구조를 그대로 복제할 경우 .gitignore에 각 .venv* 폴더를 반드시 추가해 레포지토리 용량이 급증하지 않도록 한다.