4강. 가상환경을 VSCode에 연결하기
0. 학습 목표
→ VSCode가 사용할 Python을 인터프리터로 연결·검증하고, 그 인터프리터로 코드를 실행하는 두 가지 방법을 익힙니다.
이번 글은 구현 중심 강의이자, 가장 중요한 강의입니다.
3강에서 "VSCode가 .venv의 존재는 알지만 사용은 아직 정해지지 않았다"고 했습니다.
VSCode에게 "코드를 실행할 때 이 .venv 안의 Python을 써라"라고 지정하는 것을 인터프리터 선택이라고 합니다.
최신 VSCode(2026년 기준, Python Environments 확장 포함)는 프로젝트 폴더를 열 때 그 안에 이미 있는 .venv를 자동으로 찾아 바로 사용하는 경우가 많지만, 그렇지 않으면 직접 선택해야 합니다.
이번 강의는 세 단계로 이어집니다.
먼저 인터프리터가 자동으로 지정됐는지 확인하고, 안 됐다면 직접 연결합니다.
연결이 됐으면 3중으로 검증하고, 마지막으로 그 인터프리터를 실제로 써서 코드를 실행합니다.
실행 버튼과 통합 터미널 중 무엇을 쓰든, 이 검증을 통과한 같은 .venv가 쓰입니다.
상태 바에서 자동 지정 여부 확인
↓
[케이스 A] 이미 .venv로 지정됨 → 바로 검증으로
[케이스 B] 아직 지정 안 됨 → 명령 팔레트로 직접 선택 → 검증
↓
3중 검증 통과 (상태 바 · 통합 터미널 · which python)
↓
실행 버튼 또는 통합 터미널로 실행 → .venv의 python이 실행됨 ← 이번 강의의 성공 지점| 구분 | 내용 |
| 이해할 것 | 인터프리터 자동/수동 지정의 의미와, 그 지정이 실행 버튼·통합 터미널 실행에 그대로 이어지는 이유 |
| 만들 것 | .venv의 Python이 인터프리터로 연결되고, 그 안에서 main.py가 실행되는 VSCode 워크스페이스 |
| 확인할 것 | 상태 바 · 통합 터미널의 (.venv) · which python 3중 검증, 그리고 실행 버튼·통합 터미널 모두에서 뜨는 실행 결과 창 |
1. 지금 상태 확인하기 — 자동 지정 여부
→ 상태 바를 먼저 확인해 자동으로 지정됐는지 보고, 아니라면 그 이유를 직접 실행해 확인합니다.
1.1 상태 바로 자동 지정 여부 확인하기
화면 맨 아래 상태 바를 봅니다.
3강에서 폴더를 워크스페이스로 열어둔 이 프로젝트에는 이미 .venv가 존재하므로,
VSCode가 그 환경을 자동으로 인터프리터로 지정했을 수 있습니다. 최신 VSCode의 Python 확장은 워크스페이스에 환경이 하나뿐이면 별도 선택 없이 바로 그 환경을 사용하는 경우가 많기 때문입니다.
| 구분 | 상태 바 표시 | 지금 할 일 |
| 자동 지정됨 (케이스 A) | Python 3.13.x ('.venv': venv) |
2번 건너뛰고 3번 검증으로 이동 |
| 수동 지정 필요 (케이스 B) | 시스템 Python 경로, 인터프리터 미지정 표시 | 아래에서 원인을 확인한 뒤 2번에서 직접 지정 |
지금 상태 바에 이미 .venv가 표시되어 있다면 자동으로 연결된 것이므로, 아래 실패 재현 없이 3번 연결 검증하기로 바로 넘어가도 됩니다. 상태 바가 시스템 Python을 가리키거나 인터프리터가 표시되지 않는다면, 아래에서 그 이유를 직접 실행해 확인합니다.
1.2 자동 지정되지 않았다면 — 실행해서 원인 보기
아직 인터프리터가 지정되지 않은 상태에서 main.py를 실행해 보겠습니다.
편집 영역에 main.py를 열고 오른쪽 위의 실행 버튼(▷)을 누릅니다.
(실행 방법은 4번에서 자세히 다루므로, 지금은 오류를 보기 위한 것입니다.)
하단 통합 터미널에 다음과 같은 메시지가 나타납니다.
Traceback (most recent call last):
File "main.py", line 2, in
from PySide6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
ModuleNotFoundError: No module named 'PySide6'
지난 시리즈에서 여러 번 본 바로 그 오류입니다.
코드는 지난 시리즈에서 정상 실행되던 그대로인데 왜 실패할까요? 원인은 어떤 Python이 실행했는가에 있습니다.
지난 시리즈 (터미널)
→ source .venv/bin/activate 로 가상환경 활성화 후 실행
→ .venv의 Python이 실행 → PySide6 있음 → 성공지금 (VSCode, 인터프리터 미지정)
→ VSCode가 기본값인 시스템 Python으로 실행
→ 시스템 Python에는 PySide6 없음 → ModuleNotFoundError ← 원인지난 강의에서 PySide6를 .venv 안에만 설치하고, 시스템 Python은 깨끗하게 유지했던 것을 떠올려 보세요.
그때 deactivate 후 pip show를 하면 시스템에서는 PySide6를 못 찾았습니다. 지금 VSCode가 겪는 것이 정확히 그 상황입니다 — 아직 .venv를 쓰라는 지시를 받지 못해 기본값인 시스템 Python으로 실행한 것입니다. 터미널에서는 activate로 이 문제를 해결했다면, VSCode에서 그에 해당하는 동작이 바로 인터프리터 선택입니다.
2. 인터프리터를 .venv로 수동으로 연결하기
→ 명령 팔레트로 인터프리터를 선택해 케이스 B를 해결하고, 필요하면 자동 지정된 환경도 바꿉니다.
인터프리터(interpreter)는 Python 코드를 실행하는 Python 실행 파일을 가리키는 말입니다.
지난 시리즈에서 which python으로 확인하던 그 python 실행 파일이 곧 인터프리터입니다.
VSCode에 "이 실행 파일로 코드를 돌려라"라고 알려주는 것이 인터프리터 선택이며, 케이스 B처럼 자동 지정이 되지 않았을 때는 물론, 케이스 A에서 자동 지정된 환경을 다른 것으로 바꾸고 싶을 때도 똑같은 방법을 씁니다.
명령 팔레트를 엽니다(Ctrl+Shift+P). 검색창에 Python: Select Interpreter를 입력하고 Enter를 누릅니다.
2강에서 배운 대로, 메뉴 위치를 외울 필요 없이 기능 이름으로 찾는 방식입니다.
그러면 VSCode가 찾은 Python 목록이 나타납니다.
목록에서 경로에 Project/.venv/bin/python이 포함된 항목을 고릅니다.
선택 후보 예시
/usr/bin/python3 ← 시스템 Python (고르지 않음)
~/Dev/Project/.venv/bin/python 3.13.x ← 이것을 선택! (우리 프로젝트의 가상환경)
여러 후보 중 반드시 프로젝트 폴더 안의 .venv 경로를 골라야 합니다.
시스템 Python을 고르면 1번에서 본 오류가 그대로 반복됩니다.
항목을 선택하는 순간, VSCode는 이 워크스페이스에서 앞으로 그 인터프리터를 쓰겠다고 기억합니다.
이 선택은 워크스페이스에 저장되므로, 다음에 이 폴더를 다시 열어도 유지됩니다.
3. 연결 검증하기 — 3중 확인
→ 세 곳에서 VSCode가 정말 .venv를 쓰고 있는지 눈으로 확인합니다.
케이스 A로 자동 지정됐든, 케이스 B에서 방금 수동으로 선택했든 "연결됐다"는 말만 믿지 않고 세 곳에서 직접 확인합니다. 지난 시리즈에서 가상환경 활성화 후 which python으로 경로를 눈으로 확인했던 것과 같은 검증 습관입니다.
3.1 확인 1 — 상태 바 표시
화면 맨 아래 상태 바(2강에서 본 맨 아래 가로 띠)를 봅니다.
인터프리터가 연결되어 있으면 이곳에 현재 연결된 Python이 표시됩니다.
화면 맨 아래 상태 바
... Python 3.13.x ('.venv': venv) ← 여기에 .venv가 표시되면 연결됨.venv와 버전이 함께 표시되면 첫 번째 확인 통과입니다. 앞으로 이 상태 바만 흘깃 봐도 "지금 VSCode가 내 가상환경을 쓰고 있구나"를 알 수 있습니다.
3.2 확인 2 — 통합 터미널의 (.venv) 표시
통합 터미널을 새로 엽니다(Terminal → New Terminal). 인터프리터가 연결되어 있으면 VSCode가 터미널을 열 때 자동으로 가상환경을 활성화해 줍니다. 그래서 프롬프트 앞에 (.venv)가 이미 붙어 있습니다.
(.venv) user@ubuntu:~/Dev/Project$ ← activate를 직접 치지 않았는데 (.venv)가 붙어 있다지난 시리즈에서는 매번 source .venv/bin/activate를 직접 입력해야 했지만, VSCode는 인터프리터를 지정해 두면 터미널을 열 때 이 활성화를 대신 해 줍니다. 인터프리터 선택 하나가 터미널 활성화까지 처리해 주는 것입니다.
3.3 확인 3 — which python으로 경로 확인
마지막으로, 지난 강의에서 하던 그 명령을 통합 터미널에서 그대로 실행합니다. 가장 확실한 검증입니다.
which python # VSCode 통합 터미널에서 실행/home/사용자명/Dev/Project/.venv/bin/python ← 시스템이 아닌 .venv 경로!지금까지 봤던 것과 똑같은 경로가 나옵니다. 시스템 /usr/bin/python3가 아니라 프로젝트 .venv 안의 Python입니다. 세 곳의 확인이 모두 .venv를 가리키면, VSCode와 가상환경의 연결이 완성된 것입니다.
| 확인 위치 | 확인 내용 | 지난 시리즈 대응 |
| 상태 바 | ('.venv': venv) 표시 |
(VSCode 고유) |
| 통합 터미널 프롬프트 | (.venv) 자동 표시 |
activate 후 프롬프트 |
which python |
.venv/bin/python 경로 |
경로 검증 그대로 |
✔ 확인 기준: 상태 바에 ('.venv': venv)가 표시되고, 통합 터미널 프롬프트에 (.venv)가 붙고, which python이 .venv/bin/python을 출력하면 연결 완료입니다. 목록에 .venv가 안 보이면 폴더를 ~/Dev/Project로 열었는지(3강) 확인하고, 명령 팔레트에서 Developer: Reload Window로 새로고침한 뒤 다시 시도하세요.
4. 검증된 인터프리터로 실행하기
→ 실행 버튼과 통합 터미널, 두 가지 방법으로 main.py를 실행하고 결과를 확인합니다.
4.1 실행 버튼으로 실행하기
편집 영역 오른쪽 위에 삼각형 모양의 실행 버튼(▷)이 있습니다. main.py를 열어둔 상태에서 이 버튼을 누릅니다.
버튼을 누르면 하단에 통합 터미널이 열리면서 실행 명령이 자동으로 입력되고, 잠시 후 "환경 재현 성공"이라는 제목의 창이 뜹니다. 1번에서 ModuleNotFoundError로 실패했던 바로 그 코드가 이번에는 성공한 것입니다.
실행 버튼이 통합 터미널에 찍은 명령을 보면 이유가 보입니다.
실행 버튼이 자동으로 입력한 명령 (예시)
/home/사용자명/Dev/Project/.venv/bin/python main.py
─────────────────────────────────────────
방금 검증한 .venv의 python으로 실행된다 ← 시스템 python3가 아니다!실행 버튼은 마법이 아닙니다. 3번에서 검증한 인터프리터, 즉 .venv/bin/python을 사용해 현재 파일을 실행하는 명령을 대신 입력해 준 것뿐입니다. 그래서 .venv 안에 있던 PySide6를 정상적으로 찾을 수 있었습니다.
4.2 통합 터미널로 실행하기
실행 버튼 말고, 지난 시리즈에서 하던 방식으로도 실행할 수 있습니다. 통합 터미널을 열고(Terminal → New Terminal) 직접 명령을 입력합니다.
python main.py # 통합 터미널에서 직접 실행역시 같은 창이 뜹니다. 여기서 눈여겨볼 것은 source .venv/bin/activate를 직접 입력하지 않았는데도 성공했다는 점입니다. 3.2에서 확인했듯, VSCode는 인터프리터가 연결된 상태에서 통합 터미널을 열면 가상환경을 자동으로 활성화해 줍니다. 프롬프트의 (.venv) 표시가 그 증거입니다.
| 방법 | 어떻게 | 편한 상황 |
| 실행 버튼 (▷) | 현재 파일을 클릭 한 번으로 실행 | 지금 열어둔 파일을 빠르게 실행할 때 |
| 통합 터미널 | python main.py 직접 입력 |
실행 인자를 붙이거나 다른 명령과 섞어 쓸 때 |
두 방법 모두 3번에서 검증한 같은 .venv를 씁니다. 자동으로 지정됐든 직접 연결했든, 한 번 제대로 검증해 두면 실행 방식과 무관하게 항상 올바른 Python이 쓰입니다.
- 인터프리터는 자동으로 지정되기도 하고(케이스 A), 수동으로 지정하기도 한다(케이스 B)
- 어느 쪽이든 상태 바 · 통합 터미널 (.venv) · which python 3중 검증으로 확인한다
- 실행 버튼과 통합 터미널 모두 검증된 같은 .venv의 python을 사용한다
- 실행 문제가 나면 가장 먼저 상태 바의 인터프리터 표시를 확인한다✔ 확인 기준: 실행 버튼(▷)과 통합 터미널의 python main.py 두 방법 모두에서 "환경 재현 성공" 창이 뜨면 이번 강의 완료입니다. 창이 안 뜨고 ModuleNotFoundError가 나면 상태 바가 ('.venv': venv)인지 먼저 확인하고, 아니라면 2번의 인터프리터 선택을 다시 진행하세요.
→ 다음 강의 (5강): 지금까지는 코드가 잘 동작했지만, 값이 잘못 나올 때는 어떻게 원인을 찾을까요? 지난 시리즈에서는 print를 여기저기 넣어 보는 것이 전부였습니다. 5강에서는 코드를 원하는 지점에서 멈춰 세우고 그 순간의 변수 값을 직접 들여다보는 디버깅을 배웁니다 — 이 시리즈의 핵심 보상입니다.