Python 인터프리터가 VSCode에서 안 잡힐 때: venv·conda·uv 점검 순서

VSCode에서 Python 파일을 열었는데 인터프리터가 비어 있거나, 분명 환경을 만들었는데 목록에 안 보이거나, 실행은 되는데 다른 버전의 Python이 잡히는 경우가 자주 있습니다. 특히 venv, conda, uv를 번갈아 써 왔다면 어디서부터 확인해야 할지 더 헷갈리기 쉽습니다.

이럴 때는 설치를 처음부터 다시 하기보다, 환경이 실제로 있는지, VSCode가 그 환경을 찾는지, 현재 워크스페이스가 다른 인터프리터를 기억하고 있는지 순서대로 나눠 보면 문제를 훨씬 빨리 찾을 수 있습니다. 아래 순서대로 보면 초보자도 어디에서 꼬였는지 판단하기 쉬워집니다.

먼저 증상을 세 가지로 나눠 보면 훨씬 쉽다

인터프리터 문제가 늘 같은 원인에서 생기는 것은 아닙니다. 크게 보면 환경이 아예 없는 경우, 환경은 있는데 VSCode가 못 찾는 경우, 선택은 됐는데 터미널이나 실행 경로가 다른 Python을 보는 경우로 나뉩니다. 이 구분만 먼저 해도 불필요한 재설치를 줄일 수 있습니다.

1단계: 환경이 실제로 존재하는지 먼저 확인한다

가장 먼저 볼 것은 VSCode가 아니라 환경 자체입니다. 인터프리터가 안 잡힐 때 의외로 흔한 경우가, 환경이 있다고 생각했지만 실제 폴더나 실행 파일이 없거나 다른 위치에 만들어진 상황입니다.

venv를 쓰는 경우

프로젝트 루트에 .venv 또는 venv 폴더가 있는지 먼저 봅니다. macOS와 Linux라면 보통 .venv/bin/python, Windows라면 .venv\Scripts\python.exe가 있어야 합니다. 이 파일이 없으면 VSCode가 못 찾는 것이 아니라 아직 쓸 인터프리터가 없는 상태에 가깝습니다.

conda를 쓰는 경우

conda env list로 환경 이름이 실제로 존재하는지 먼저 확인합니다. 환경 이름은 기억나는데 삭제되었거나, 다른 쉘에서는 보이는데 VSCode 터미널에서는 안 보이는 경우도 있기 때문에 목록 확인이 가장 빠릅니다.

uv를 쓰는 경우

uv는 프로젝트 중심으로 환경을 다루는 경우가 많아서, uv sync 이후 프로젝트 폴더 안의 .venv가 만들어졌는지 확인하는 편이 빠릅니다. uv를 쓴다고 해서 VSCode가 별도의 “uv 인터프리터”를 잡는 것이 아니라, 실제로는 프로젝트의 가상환경 Python 실행 파일을 찾는 흐름으로 이해하면 덜 헷갈립니다.

2단계: VSCode가 새 환경을 다시 찾게 만든다

환경은 분명 있는데 목록에 안 보인다면, 그다음부터는 VSCode의 검색과 선택 문제일 가능성이 큽니다. 특히 환경을 VSCode를 켠 뒤에 만든 경우, 목록 갱신이 바로 안 보이는 일이 있습니다.

인터프리터를 직접 다시 선택해 본다

명령 팔레트에서 Python: Select Interpreter를 열고 목록을 다시 봅니다. 방금 만든 환경이 자동으로 안 보이면, 프로젝트 폴더를 다시 열거나 창을 새로고침한 뒤 다시 확인하는 것만으로 해결되는 경우가 적지 않습니다.

출처: Visual Studio Code 공식 문서

프로젝트 폴더를 잘못 연 것은 아닌지 본다

상위 폴더가 아니라 하위 폴더만 열었거나, 반대로 프로젝트 루트보다 위쪽을 열어 둔 경우 환경 인식이 어긋날 수 있습니다. 예를 들어 .venv는 프로젝트 루트에 있는데, VSCode는 그 안의 src 폴더만 열고 있으면 예상과 다르게 보일 수 있습니다.

워크스페이스가 예전 인터프리터를 기억하는지 본다

어제는 conda를 쓰고 오늘은 venv를 만들었다면, 현재 워크스페이스가 예전 선택을 그대로 들고 있을 수 있습니다. 이런 때는 새 환경을 다시 선택해 저장하고, 실행과 디버깅도 같은 인터프리터를 보도록 맞춰 주는 편이 안전합니다.

3단계: 터미널이 다른 Python을 보고 있지 않은지 확인한다

상태바에 보이는 인터프리터와 터미널에서 실제로 실행되는 Python이 다른 경우가 가장 헷갈립니다. 이때는 VSCode 자체가 틀렸다기보다, 쉘 초기화 파일이나 PATH 우선순위 때문에 터미널이 다른 실행 파일을 먼저 보고 있는 경우가 많습니다.

터미널에서 현재 Python 경로를 먼저 찍어 본다

macOS와 Linux에서는 which python 또는 which python3, Windows에서는 where python을 확인하면 지금 터미널이 어느 Python을 먼저 보는지 알 수 있습니다. 여기서 나온 경로가 VSCode 상태바의 인터프리터 경로와 다르면, 문제는 인터프리터 선택보다 PATH 또는 활성화 흐름 쪽일 가능성이 큽니다.

터미널 자동 활성화가 기대와 다를 수 있다

인터프리터를 골랐다고 해서 모든 터미널 세션이 같은 타이밍에 완벽하게 바뀌는 것은 아닙니다. 이미 열려 있던 터미널 탭은 이전 환경을 유지할 수 있기 때문에, 인터프리터를 다시 고른 뒤에는 새 터미널을 열어 확인하는 편이 더 정확합니다.

터미널 경로와 쉘 설정이 함께 꼬였는지 확인하려면 VSCode 터미널 기본기 2026 를 함께 보면 원인을 더 빨리 좁힐 수 있습니다.

실행과 디버깅이 다르게 보일 수도 있다

파일 실행은 맞는데 디버깅만 다른 Python으로 도는 경우라면, 디버깅 설정이 예전 인터프리터 기준으로 남아 있을 수 있습니다. 이때는 인터프리터를 다시 선택한 뒤 디버깅도 같은 환경을 쓰는지 같이 확인하는 편이 좋습니다.

4단계: venv·conda·uv가 섞였을 때는 하나만 기준으로 잡는다

문제를 오래 끄는 가장 흔한 패턴은 프로젝트 안에 여러 방식의 환경이 함께 있는 경우입니다. 예를 들어 .venv도 있고 conda 환경도 있고, uv로 다시 패키지를 관리하고 있다면 사람도 헷갈리고 VSCode도 예상과 다르게 보일 수 있습니다.

프로젝트마다 주환경을 하나만 정한다

하나의 프로젝트에서는 “이 프로젝트는 .venv를 기준으로 본다” 또는 “이 프로젝트는 conda 환경 이름으로 본다”처럼 기준을 먼저 정하는 편이 좋습니다. uv를 쓰더라도 실제 실행 환경은 보통 프로젝트의 .venv를 기준으로 맞추면 이해가 쉬워집니다.

환경 이름이 비슷하면 더 헷갈린다

venv, .venv, myenv, conda의 base, 별도로 만든 Python 버전이 한꺼번에 있으면 목록에서 잘못 고르기 쉽습니다. 이럴 때는 프로젝트마다 이름을 단순하게 유지하고, 필요 없는 예전 환경은 정리하는 편이 이후 오류를 줄입니다.

지금 설치 방식보다 더 중요한 것은 일관성이다

venv가 더 낫냐, conda가 더 낫냐, uv가 더 낫냐보다 중요한 것은 한 프로젝트 안에서 흐름을 섞지 않는 것입니다. 설치는 uv로 하고 실행은 오래된 conda 환경으로 하고, VSCode는 또 다른 전역 Python을 보게 두면 인터프리터 문제는 반복되기 쉽습니다.

5단계: 그래도 안 보이면 이렇게 좁혀 보면 된다

여기까지 했는데도 해결되지 않으면, 지금부터는 무엇이 문제인지 한 번에 다 고치려 하지 말고 원인을 좁혀 보는 편이 좋습니다. 가장 쉬운 방법은 새 폴더에서 아주 작은 테스트 환경을 하나 만드는 것입니다.

공식 문서에서 기본 흐름을 확인했다면, 실제로 디버깅과 개발환경 선택을 어떤 기준으로 나눌지 아래 글까지 함께 보면 정리가 더 쉬워집니다.

자주 묻는 질문

---

Python 인터프리터 문제는 설치 자체보다 환경 기준이 섞여 생기는 경우가 많아서, 먼저 하나의 프로젝트에 하나의 실행 기준을 정해 두는 편이 가장 안정적입니다.