Python 오류 해결: VS Code에서 Python이 실행되지 않을 때

 저도 처음에 PATH에서 막혔는데, Python을 분명 설치했는데도 VS Code에서 코드를 실행하면 "python은 내부 또는 외부 명령... 이 아닙니다"라는 메시지만 계속 나와서 몇 시간을 헤맸던 기억이 있습니다. 설치 프로그램을 여러 번 지웠다 다시 깔아봐도 마찬가지였는데, 알고 보니 문제는 Python 설치 자체가 아니라 VS Code가 Python을 찾아가는 경로 설정에 있었습니다. 이 글에서는 그때 겪었던 시행착오를 바탕으로, VS Code에서 Python이 실행되지 않을 때 확인해야 할 원인들을 순서대로 정리해보겠습니다.



Python이 실행되지 않는 근본 원인

VS Code와 Python의 연결 구조 이해하기

VS Code는 그 자체로 Python을 실행하는 프로그램이 아닙니다. 컴퓨터에 별도로 설치된 Python 인터프리터를 찾아서 연결해주는 편집기 역할을 할 뿐입니다. 이 연결 구조를 이해하지 못하면 오류가 발생했을 때 엉뚱한 곳에서 원인을 찾게 됩니다.

비유하자면 VS Code는 마치 리모컨과 같고, Python은 그 리모컨이 조작하는 TV 본체와 같습니다. 리모컨 배터리가 아무리 좋아도 TV와 연결이 제대로 안 되어 있으면 화면이 켜지지 않는 것처럼, VS Code가 아무리 잘 설치되어 있어도 Python 인터프리터와의 연결이 어긋나 있으면 코드가 실행되지 않습니다.

자주 발생하는 오류 유형

  • 터미널에서 python 명령어 자체를 인식하지 못하는 경우
  • VS Code가 엉뚱한 Python 인터프리터를 바라보고 있는 경우
  • 확장 프로그램(Python Extension) 미설치로 인한 실행 오류
  • 가상환경이 활성화되지 않아 발생하는 모듈 인식 오류
  • 파일 경로에 한글이나 공백이 포함되어 발생하는 오류

PATH 환경변수 문제 해결하기

python 명령어를 인식하지 못하는 경우

VS Code 터미널에 python이라고 입력했는데 명령어를 찾을 수 없다는 오류가 나온다면, Python 설치 과정에서 "Add Python to PATH" 옵션을 체크하지 않았을 가능성이 큽니다.

이 경우 Python을 재설치하면서 옵션을 다시 체크하는 방법도 있지만, 이미 설치되어 있는 상태라면 환경변수를 수동으로 등록하는 방법도 있습니다.

  1. Windows 검색창에 "환경 변수 편집"을 입력해 실행합니다
  2. 시스템 변수의 Path 항목에 Python 설치 경로를 추가합니다
  3. 새 터미널을 열어 변경 사항이 적용되었는지 확인합니다
python --version

환경변수를 변경한 뒤에는 반드시 새 터미널 창을 열어서 확인해야 하는데, 기존에 열려 있던 터미널은 변경 사항을 반영하지 못하기 때문입니다.

인터프리터 설정 문제 해결하기

잘못된 인터프리터가 선택된 경우

컴퓨터에 여러 개의 Python 버전이나 가상환경이 설치되어 있다면, VS Code가 지금 프로젝트와 맞지 않는 인터프리터를 바라보고 있을 가능성이 있습니다. 이런 상황에서는 분명 터미널에서 패키지를 설치했는데도 코드에서는 "모듈을 찾을 수 없다"는 오류가 발생합니다.

이는 마치 우편물을 특정 주소로 보냈는데, 정작 받는 사람은 이사 간 옛날 집에서 우편물을 기다리고 있는 상황과 비슷합니다. 발신 주소(터미널)와 수신 주소(VS Code 인터프리터)가 일치해야 제대로 전달이 됩니다.

VS Code 하단 상태바를 확인해서 현재 선택된 인터프리터를 직접 눈으로 확인하는 것이 가장 빠른 해결 방법입니다.




인터프리터 다시 선택하기

명령 팔레트를 열어 인터프리터를 직접 다시 선택할 수도 있습니다.

  1. Ctrl+Shift+P를 눌러 명령 팔레트를 엽니다
  2. "Python: Select Interpreter"를 검색해서 선택합니다
  3. 목록에서 현재 프로젝트에 맞는 인터프리터를 선택합니다


Python 확장 프로그램과 가상환경 점검하기

Python 확장 프로그램 설치 확인

VS Code에서 Python 코드를 제대로 실행하려면 마이크로소프트에서 제공하는 공식 Python 확장 프로그램이 반드시 설치되어 있어야 합니다. 이 확장이 없으면 문법 강조나 인터프리터 선택 기능 자체가 동작하지 않아, 겉보기에는 아무 문제가 없어 보여도 실행이 되지 않는 경우가 있습니다.


가상환경이 활성화되지 않은 경우

프로젝트마다 가상환경을 사용하고 있다면, 터미널을 새로 열 때마다 가상환경이 자동으로 활성화되는지 확인해야 합니다. 활성화되지 않은 상태에서 코드를 실행하면 가상환경 안에 설치했던 패키지들을 전역 Python이 인식하지 못해 오류가 발생합니다.

# Windows 기준 가상환경 활성화
venv\Scripts\activate

터미널 프롬프트 앞에 (venv)와 같은 표시가 나타난다면 가상환경이 정상적으로 활성화된 것입니다.

파일 경로와 이름 확인하기

의외로 자주 발생하는 문제 중 하나는 프로젝트 폴더 경로에 한글이나 공백이 포함되어 있는 경우입니다. 일부 환경에서는 이런 경로 때문에 실행 오류가 발생할 수 있으므로, 가능하다면 영문과 숫자로만 이루어진 경로에서 작업하는 것을 권장합니다.

마무리

지금까지 VS Code에서 Python이 실행되지 않을 때 확인해야 할 원인들을 순서대로 정리해봤습니다. 대부분의 실행 오류는 PATH 환경변수, 인터프리터 설정, 확장 프로그램, 가상환경이라는 몇 가지 지점에서 발생하므로, 오류 메시지를 보고 당황하기보다는 이 네 가지를 차례로 점검해보는 것이 빠른 해결의 지름길입니다.

핵심 내용을 정리하면 다음과 같습니다.

  • python 명령어를 인식하지 못한다면 PATH 환경변수 등록 여부를 먼저 확인해야 합니다
  • VS Code 하단 상태바에서 올바른 Python 인터프리터가 선택되어 있는지 확인해야 합니다
  • Python 확장 프로그램이 설치되어 있지 않으면 정상적인 실행이 불가능합니다
  • 가상환경을 사용 중이라면 터미널에서 반드시 활성화 여부를 확인해야 합니다
  • 프로젝트 경로에 한글이나 공백이 포함되어 있다면 영문 경로로 변경하는 것이 안전합니다

다음 글에서는 Python 실행 과정에서 자주 마주치는 ModuleNotFoundError와 SyntaxError 같은 구체적인 오류 메시지별 해결 방법을 더 자세히 다뤄보도록 하겠습니다.


댓글

댓글 쓰기

이 블로그의 인기 게시물

1.Python 설치부터 실행까지 10분 만에 끝내기 — 초보자도 바로 따라 하는 완벽 가이드

이미지
프로그래밍을 처음 시작하기로 결심한 날, 많은 분들이 유튜브를 켜고 이렇게 검색합니다. "파이썬 설치 방법." 영상을 따라가다 보면 어느 순간 화면 속 강사의 컴퓨터와 내 컴퓨터가 달라지기 시작합니다. "명령어를 찾을 수 없습니다", "PATH가 설정되지 않았습니다" 같은 오류 메시지가 등장하고, 결국 설치도 못 한 채 탭을 닫아버리게 됩니다. 이 글은 바로 그 지점을 해결하기 위해 쓰였습니다. 설치 과정에서 실제로 막히는 이유, 놓치기 쉬운 체크박스 한 칸의 의미, 그리고 첫 코드를 실행하는 순간까지 — 군더더기 없이 안내해 드리겠습니다. 저도 처음 설치때 1시간을 소비 했습니다.이제 해매지 마세요~!!  Python이 실제로 하는 일 — 번역가 비유로 이해하기 Python을 설치하기 전에, Python이 무엇인지 정확히 이해하면 이후 과정이 훨씬 자연스러워집니다. 컴퓨터는 본래 0과 1, 즉 기계어만 이해합니다. 사람이 "파일을 열어줘"라고 말해도 컴퓨터는 알아듣지 못합니다. Python은 바로 이 간극을 메우는 번역가 역할을 합니다. 우리가 사람에게 말하듯 작성한 코드를 컴퓨터가 이해할 수 있는 언어로 변환해 주는 것입니다. 여기서 핵심이 있습니다. 번역가가 없으면 대화가 불가능합니다. Python을 설치한다는 것은 곧 이 번역가를 내 컴퓨터에 고용하는 일입니다. 설치가 완료된 순간부터 여러분의 컴퓨터는 Python이라는 언어를 이해하기 시작합니다. Python을 선택해야 하는 이유 문법이 자연어에 가깝습니다 — if 날씨 == "맑음": 나가기() 처럼, 코드가 한국어 문장 구조와 유사합니다. 범용성이 압도적입니다 — 데이터 분석, 웹 개발, 자동화, AI 모델 구축까지 하나의 언어로 가능합니다. 생태계가 방대합니다 — 전 세계 개발자들이 만든 50만 개 이상의 라이브러리가 무료로 제공됩니다. 취업 시장에서 가장 수요가 높습니다 ...
자세한 내용 보기

30.Python pyautogui로 마우스와 키보드 자동화하기: VSCode 실전 가이드

이미지
 저도 처음에 PATH에서 막혔는데, 매일 반복되는 사내 시스템 클릭 작업을 자동화해보려고 pyautogui 를 설치했지만 VSCode에서 실행할 때마다 "No module named 'pyautogui'"라는 오류만 계속 나왔던 기억이 있습니다. 분명 터미널에서는 설치가 잘 됐다고 나왔는데, 알고 보니 VSCode가 바라보고 있던 Python 인터프리터 경로와 제가 패키지를 설치한 경로가 서로 달랐던 것이 원인이었습니다. 인터프리터를 올바르게 맞춰주고 나서야 마우스가 제 손을 대신해 화면을 클릭하고 키보드를 두드리는 신기한 광경을 볼 수 있었습니다. 이번 글에서는 그때의 시행착오를 바탕으로, VSCode 환경에서 Python pyautogui를 활용해 마우스와 키보드를 자동화하는 방법을 정리해보려 합니다. pyautogui란 무엇인가 마우스와 키보드를 코드로 제어하는 라이브러리 pyautogui 는 Python 코드로 마우스 움직임과 클릭, 키보드 입력을 프로그래밍적으로 제어할 수 있게 해주는 GUI 자동화 라이브러리입니다. 웹 브라우저나 애플리케이션 내부 요소를 직접 다루는 Selenium과 달리, pyautogui는 화면 좌표와 픽셀을 기준으로 동작하기 때문에 특정 프로그램에 국한되지 않고 컴퓨터 화면에서 벌어지는 거의 모든 작업을 자동화할 수 있습니다. 비유하자면 pyautogui는 마치 컴퓨터 앞에 보이지 않는 손 하나를 앉혀두는 것과 같습니다. 이 손은 사람이 시키는 대로 정확한 좌표를 클릭하고, 정해진 문장을 타이핑하며, 화면 속 특정 이미지를 찾아내기까지 하는데, 사람과 다른 점은 지치지 않고 똑같은 작업을 몇 번이고 정확하게 반복한다는 것입니다. pyautogui가 유용한 대표적인 상황 반복적인 클릭 작업이 많은 사내 시스템 업무 자동화 특정 시간마다 실행해야 하는 프로그램 작업 자동화 게임이나 소프트웨어 테스트 시 반복 입력 시뮬레이션 화면 캡처와 이미지 인식을 결합한 자동 작업 흐름 구성 매크로 프로그램을 대...
자세한 내용 보기

29.Python subprocess로 외부 명령어 실행하기: VSCode 실전 활용법

이미지
저도 처음에는 회사에서 매일 반복하던 번거로운 서버 배포 작업을 자동화해 보려고, 파이썬 스크립트 안에 깃( git ) 명령어를 넣어 실행하는 코드를 짰던 것이 시작이었습니다. 분명 내 터미널에 직접 입력할 때는 잘만 되던 명령어가, 파이썬 코드로 실행하니 자꾸 FileNotFoundError 만 뱉어내서 도대체 뭐가 문제인지 몇 시간이나 소스 코드 이 줄 저 줄을 뜯어고치며 밤새 삽질을 했습니다. 알고 보니 코드가 아니라 VS Code가 명령 프로그램의 위치를 찾지 못하는 'PATH 환경변수' 문제였죠. 실행 경로를 명시해 주자마자 스크립트가 배포 작업을 알아서 척척 단 5초 만에 끝내는 걸 보고 , 저는 이 파이썬 자동화의 강력함에 완전히 매료되었습니다. 이번 글에서는 그때의 시행착오를 바탕으로 subprocess 를 활용해 외부 명령어를 안전하게 제어하는 방법을 정리해 보겠습니다. Python 코드 안에서 터미널 명령어를 직접 실행하고 싶었던 적이 있으신가요? 예를 들어 git , ffmpeg , curl 같은 외부 프로그램을 Python 스크립트 안에서 자동으로 호출하고 그 결과를 받아와야 하는 경우가 생각보다 자주 발생합니다. 이럴 때 필요한 것이 바로 subprocess 모듈이며, 이를 활용하면 Python이 마치 터미널을 대신 조작하는 것처럼 외부 프로그램을 자유자재로 실행할 수 있습니다. 이번 글에서는 VSCode 환경에서 Python subprocess를 활용해 외부 명령어를 실행하고 결과를 처리하는 방법을 실전 예제와 함께 정리해보겠습니다. subprocess란 무엇인가 Python에서 외부 프로세스를 실행하는 표준 모듈 subprocess 는 Python 표준 라이브러리에 내장된 모듈로, Python 코드 안에서 운영체제의 명령어나 다른 프로그램을 새로운 프로세스로 실행할 수 있게 해줍니다. 쉽게 말해 여러분이 평소 터미널에 직접 타이핑하던 명령어를, Python 코드가 대신 입력해주고 그 결과까지 받아와주는 것이...
자세한 내용 보기