Python에서 ModuleNotFoundError 발생 시 VS Code에서 확인해야 할 점

Programming/Python

마실개 2025. 4. 26. 16:13

Python 프로젝트를 진행하다 보면, 외부 라이브러리를 설치했음에도 불구하고 ModuleNotFoundError가 발생하는 경우가 종종 있다. 예를 들어 다음과 같은 오류 메시지를 볼 수 있다.

이 글에서는 위와 같은 오류가 발생하는 일반적인 원인과, VS Code 환경에서 확인하고 조치할 수 있는 방법을 정리한다. 특히 가상환경을 사용하지 않고 Python을 운영체제에 전역으로 설치해 사용하는 개발자를 위한 내용을 중심으로 설명한다.

ModuleNotFoundError는 Python에서 특정 모듈을 불러오려고 했으나 해당 모듈을 찾을 수 없을 때 발생하는 오류다. 이 오류가 발생하는 이유는 다음 중 하나다.

Python 인터프리터는 말 그대로 Python 코드를 실행하는 실행 환경이다. 하나의 시스템에 Python이 여러 버전 설치되어 있는 경우가 많으며, 각 버전마다 독립적으로 패키지를 설치하고 실행할 수 있다.

VS Code는 프로젝트를 열었을 때 자동으로 인터프리터를 선택하지만, 항상 사용자가 원하는 Python 실행 환경과 일치하는 것은 아니다. 예를 들어 VS Code는 프로젝트 내 .venv 가상환경을 자동으로 우선시하여 선택하는 경향이 있다.

가상환경은 프로젝트별로 독립적인 의존성 관리를 위해 권장되는 방식이지만, 개발자가 의도적으로 사용하지 않으려는 경우도 있다. 이럴 경우 VS Code의 자동 가상환경 선택 기능이 오히려 문제가 될 수 있다.

다음은 실제 발생했던 사례다.

Python 3.13.2이 시스템에 설치되어 있었고, pyperclip은 전역 인터프리터 환경에서 pip install pyperclip을 통해 설치하였다.
그러나 VS Code는 자동으로 .venv 폴더 내에 있는 가상환경 인터프리터 Python 3.13.2 ('.venv': venv)를 선택하고 있었고, 이 환경에는 pyperclip이 설치되어 있지 않았다.
결과적으로 ModuleNotFoundError가 발생했다.

이 문제를 해결하기 위해 다음과 같은 절차를 따를 수 있다.

VS Code 하단의 Python 버전 표시 영역을 클릭한다.
나타나는 인터프리터 목록에서 전역 Python 인터프리터를 선택한다.
- 예: Python 3.13.2 64-bit
- .venv 또는 venv 표시가 없는 것을 선택해야 한다.
변경 후 Python 파일을 다시 실행하면 모듈이 정상적으로 인식되는 것을 확인할 수 있다.

which python 혹은 python3     # macOS / Linux
where python 혹은 python3       # Windows

pip show pyperclip

이렇게 하면 현재 선택된 Python이 어느 위치에 있는지, pyperclip이 설치된 위치와 일치하는지 확인할 수 있다.

ModuleNotFoundError는 설치 여부뿐 아니라 사용 중인 인터프리터와 모듈 설치 위치의 불일치가 원인이 될 수 있다.
VS Code는 기본적으로 .venv 등 가상환경을 자동으로 선택하므로, 가상환경을 사용하지 않을 경우 수동으로 인터프리터를 변경해주어야 한다.
인터프리터가 어떤 Python 실행 파일을 가리키고 있는지 항상 명확히 확인할 필요가 있다.