VS Code에서 파이썬이 안 돌아갈 때 | No module named부터 한글 깨짐까지 오류별 해결

코드는 분명 맞는데 VS Code에서 실행을 누르면 빨간 글씨만 쏟아질 때가 있습니다. 파이썬 입문자가 가장 많이 막히는 지점은 문법이 아니라 "어떤 파이썬이 이 코드를 실행하고 있나"입니다.

VS Code에서 파이썬이 안 돌아가는 흔한 원인은 "패키지를 설치한 파이썬"과 "VS Code가 실행하는 파이썬"이 서로 다른 것이다. 프로젝트 폴더에 가상환경(.venv)을 만들고, VS Code 아래쪽 상태 표시줄이나 명령 팔레트의 Python: Select Interpreter로 그 .venv를 고른 뒤, 그 안에서 python -m pip로 설치하면 No module named 오류와 externally-managed-environment 오류가 함께 풀린다. 윈도우에서 python 명령이 안 되면 py 명령과 앱 실행 별칭을 확인하고, 한글이 깨지면 UTF-8 모드(PYTHONUTF8=1)를 켠다.

목차

1. 오류 메시지부터 읽는다

2. 가상환경을 만들고 그 안에 설치한다

3. VS Code가 그 가상환경을 쓰게 한다

4. 윈도우에서 python이 안 되거나 한글이 깨질 때

5. 파이썬 3.10을 쓰고 있다면

1. 오류 메시지부터 읽는다

파이썬은 컴퓨터에 여러 개가 깔려 있는 경우가 많습니다. 맥에는 운영체제용 파이썬, 홈브루로 설치한 파이썬이 따로 있을 수 있고, 윈도우에는 마이크로소프트 스토어판과 python.org 설치판이 함께 있기도 합니다. 터미널에서 설치한 패키지가 VS Code에서 안 보이는 건 대개 이 둘이 서로 다른 파이썬이기 때문입니다.

맥에서 직접 실행한 결과를 재구성한 화면

위 화면은 requests를 설치하지 않은 파이썬으로 코드를 실행했을 때 나온 실제 오류입니다. 마지막 줄의 오류 이름이 원인을 알려 줍니다. 아래 표에서 내 화면의 마지막 줄을 찾아보세요.

마지막 줄에 보이는 말	무슨 뜻인가	먼저 할 일
ModuleNotFoundError: No module named	대개 실행 중인 파이썬에 그 패키지가 없음	인터프리터 확인 → 가상환경 안에 설치
python: command not found / 인식되지 않음	python이라는 명령을 못 찾음	맥은 python3, 윈도우는 py로 확인
error: externally-managed-environment	시스템 파이썬에 바로 설치하는 걸 막음	가상환경을 만들어 그 안에 설치
파일을 읽을 때 한글 오류(UnicodeDecodeError 등)	파일 기본 인코딩이 UTF-8이 아님	encoding="utf-8" 지정 또는 UTF-8 모드

2. 가상환경을 만들고 그 안에 설치한다

가장 확실한 해결책은 프로젝트마다 전용 파이썬 방(가상환경)을 만드는 것입니다. 방 안에 설치한 패키지는 그 방의 파이썬만 씁니다. 아래 명령은 맥 기준이고, 직접 실행해 확인했습니다.

맥·리눅스 터미널(프로젝트 폴더에서)

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python app.py

맥에서 직접 실행한 과정을 재구성한 화면

활성화가 되면 프롬프트 앞에 (.venv)가 붙습니다. 이 표시가 있을 때 설치해야 방 안에 들어갑니다. pip 대신 python -m pip로 쓰면 지금 실행 중인 파이썬에 정확히 설치된다는 점도 기억해 두세요.

윈도우 PowerShell(프로젝트 폴더에서)

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install requests

주의 윈도우 PowerShell에서 Activate.ps1 실행이 막히면 스크립트 실행 정책 때문일 수 있습니다. 활성화 없이도 VS Code에서 .venv를 인터프리터로 고르면 실행 버튼은 그 파이썬을 쓰니, 먼저 그렇게 실행해 보고 터미널 활성화는 실행 정책을 따로 확인하세요.

맥에서 직접 실행한 결과를 재구성한 화면

홈브루로 설치한 파이썬에 바로 pip install을 하면 위처럼 거부됩니다. 오류 문구에도 "가상환경을 쓰라"고 적혀 있습니다. --break-system-packages 같은 우회 옵션으로 밀어붙이기보다 가상환경을 만드는 쪽이 안전합니다.

핵심 No module named와 externally-managed-environment는 같은 처방으로 풀립니다. 프로젝트 폴더에 .venv를 만들고, 그 안에서 설치하고, VS Code가 그 .venv를 쓰게 하면 됩니다.

3. VS Code가 그 가상환경을 쓰게 한다

VS Code 공식 문서를 바탕으로 재구성한 예시 화면

VS Code 공식 문서에 따르면 지금 쓰는 파이썬은 창 아래쪽 상태 표시줄에 표시되고, 거기를 누르거나 명령 팔레트(맥 Cmd+Shift+P, 윈도우 Ctrl+Shift+P)에서 Python: Select Interpreter를 실행해 바꿀 수 있습니다. 여기서 고른 환경이 코드 실행, 디버깅, 자동 완성에 함께 쓰입니다.

출처: VS Code 공식 문서 갈무리

1. VS Code로 프로젝트 폴더를 엽니다(파일 하나만 열지 말고 폴더째).
2. .py 파일을 열고 아래 상태 표시줄의 파이썬 버전을 누릅니다.
3. 목록에서 이름에 .venv가 들어간 항목을 고릅니다.
4. 터미널을 새로 열면 그 환경이 자동으로 활성화됩니다.

아직 가상환경이 없다면 Python 사이드바의 Environment Managers에서 +를 누르는 Quick Create로 만들 수 있습니다. 문서 설명대로라면 최신 파이썬으로 .venv를 만들고, requirements.txt나 pyproject.toml이 있으면 의존성까지 설치한 뒤 그 환경을 선택해 줍니다. 별도 설정을 하지 않으면 VS Code는 작업 폴더 안의 .venv를 먼저 고릅니다.

주의 실행 버튼(▷)이 아예 안 보이면 마켓플레이스에서 Microsoft가 만든 Python 확장이 설치돼 있는지, 연 파일의 확장자가 .py인지 확인하세요. 확장을 새로 깔았다면 VS Code를 한 번 다시 여는 편이 빠릅니다.

4. 윈도우에서 python이 안 되거나 한글이 깨질 때

python.org의 윈도우 사용 문서는 python을 입력했을 때 "명령을 찾을 수 없다"는 오류가 나거나 스토어 앱이 열리면 먼저 Python install manager를 설치했는지 확인하라고 안내합니다. 이미 설치했다면 시작 메뉴에서 "Manage app execution aliases"(앱 실행 별칭 관리)를 열어 Python (default) 별칭이 켜져 있는지 보고, 켜져 있어도 껐다 켜서 새로 고치라고 합니다. py와 pymanager 명령이 되는지, PATH에 해당 경로가 들어 있는지도 함께 확인합니다.

python.org 윈도우 문서를 바탕으로 재구성한 예시 화면

한글 문제는 먼저 어디서 깨지는지 구분하세요. 같은 문서는 콘솔 입출력이 이미 UTF-8을 기본으로 쓴다고 설명합니다. 그래서 흔히 걸리는 곳은 UTF-8로 저장된 파일을 open()으로 읽을 때입니다. 윈도우의 기본 텍스트 파일 인코딩이 UTF-8이 아니면 한글이 든 파일에서 오류가 나거나 글자가 깨집니다. 코드에 encoding="utf-8"을 직접 적는 게 가장 확실하고, 문서대로 -X utf8 옵션이나 PYTHONUTF8=1 환경 변수로 UTF-8 모드를 켜면 기본 인코딩 자체가 UTF-8로 바뀝니다. 다만 이 값을 시스템 기본 환경 변수에 넣으면 그 PC의 모든 파이썬에 적용되니, 처음에는 위 화면처럼 PowerShell 창 하나에서만 시험해 보세요.

윈도우 PowerShell, 이 창에서만 UTF-8 모드

$env:PYTHONUTF8=1
python hello.py

핵심 윈도우 오류 문구는 PC와 설치 방식마다 다릅니다. 이 글은 윈도우 화면을 직접 재현하지 않았고, 확인용 명령만 공식 문서 기준으로 모았습니다.

5. 파이썬 3.10을 쓰고 있다면

python.org 공식 블로그(10월 1일)는 3.10.22가 파이썬 3.10의 마지막 릴리스이며, 3.10은 지원이 끝나 더 이상 보안 업데이트를 받지 않는다고 밝혔습니다. 3.11은 2027년 10월까지 보안 수정만 받고, 3.10.22와 3.11.17은 윈도우·맥 설치 파일 없이 소스로만 배포됩니다.

출처: python.org 공식 블로그 갈무리

강의나 책 때문에 3.10을 깔았다면, 새 가상환경은 설치 파일이 제공되는 최신 버전으로 만드는 편이 낫습니다. 가상환경은 버전마다 새로 만들면 되므로 기존 프로젝트를 지우지 않아도 됩니다.

상황별 3줄 선택 가이드

• No module named가 뜬다 → 상태 표시줄에서 .venv를 골랐는지부터 확인.
• pip가 설치를 거부한다 → 우회 옵션 말고 가상환경을 만들고 그 안에서 설치.
• 윈도우에서 python 자체가 안 된다 → py 명령과 앱 실행 별칭부터 확인.

Q. 터미널에서는 되는데 VS Code 실행 버튼으로는 안 돼요.

터미널과 VS Code가 서로 다른 파이썬을 쓰고 있을 가능성이 큽니다. 버전 숫자만으로는 부족하니 터미널에서 python -c "import sys; print(sys.executable)"로 실행 파일 경로를 확인하고, VS Code에서 고른 환경의 경로와 같은지 비교하세요. 다르면 Python: Select Interpreter로 맞추면 됩니다.

Q. .venv 폴더를 깃허브에 올려도 되나요?

올리지 않는 편이 맞습니다. .venv는 PC마다 새로 만드는 폴더입니다. 필요한 패키지 목록은 requirements.txt나 pyproject.toml로 공유하세요.

Q. pip 대신 uv를 써도 되나요?

됩니다. VS Code 문서는 uv가 설치돼 있으면 가상환경 만들기와 패키지 설치에 uv를 자동으로 쓴다고 설명합니다.

Q. 파이썬 3.15는 바로 써도 되나요?

입문 단계라면 이미 정식으로 나온 최신 버전으로 시작하는 편이 무난합니다. 새 버전은 쓰는 라이브러리가 지원하는지 확인한 뒤 옮기세요.

3줄 핵심 요약

1. VS Code에서 파이썬이 안 도는 흔한 원인은 설치한 파이썬과 실행하는 파이썬이 다른 것이다.
2. 프로젝트에 .venv를 만들고, Python: Select Interpreter로 고르고, 그 안에서 python -m pip로 설치하자.
3. 윈도우는 py 명령·앱 실행 별칭, 파일 한글 오류는 encoding 지정이나 UTF-8 모드로 풀고, 3.10은 지원이 끝났다.

마치며

지금 열어 둔 프로젝트에서 VS Code 아래 상태 표시줄을 한 번 보세요. 거기 적힌 파이썬이 .venv가 아니라면, 오늘 겪은 오류의 절반은 그 한 칸에서 시작된 것입니다.

NEXT READ

이어서 읽어 볼 글

01  VSCode 설치부터 첫 사용까지 · 윈도우 초보자 따라하기

02  VS Code 확장, 뭘 깔고 뭘 안 깔까 · 설치 전 체크리스트

#VSCode파이썬,#파이썬실행안됨,#ModuleNotFoundError,#파이썬가상환경,#venv,#인터프리터선택,#pip오류,#파이썬한글깨짐,#파이썬310지원종료,#코드노트