Python 및 .venv 설정 VS Code에서
Windows 시스템에서 VS Code를 사용하여 해석기 및 가상 환경 문제 해결
0조회
이 가이드는 Windows 시스템에서 Visual Studio Code에서 Python 개발 환경을 진단, 설정 및 구현하는 최종 기술 절차를 제공합니다. winget 또는 Microsoft Store의 비표준 경로를 포함한 글로벌 해석기 올바른 할당부터, .venv에서 의존성의 자동화 및 설치에 이르기까지 포함합니다.
예측 가능한 개발 환경을 보장하기 위해, 각 프로젝트의 실행 엔진 및 의존성 패키지에서 사용자 인터페이스를 분리하는 것이 필수적입니다.
- Visual Studio Code (UI/Editor): 텍스트 편집기 및 통합 개발 환경으로서 엄격하게 작동합니다. Python 엔진을 내장하지 않으며, 코드 실행을 외부 해석기로 위임합니다.
- Python Engine (
python.exe): 코드 지시문을 처리하고 해석하는 데 책임이 있는 바이너리입니다. 시스템에서 직접 실행되거나 하위 환경 내에서 실행됩니다.
글로벌 환경 vs. 가상 환경
Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»- Python 글로벌: 시스템 기본 설치에 해당합니다. 초기 템플릿으로 작동하며, 다른 프로젝트 간 의존성 충돌을 방지하기 위해 외부 패키지로 수정해서는 안 됩니다.
- 가상 환경 (
.venv): 고립된 하위 디렉토리로, 자체 Python 바이너리와 의존성 트리가 포함됩니다 (site-packages).
┌──────────────────────────────────────────────────────────┐
│ Sistema Operativo │
│ (Python Global - Instalación base libre de paquetes) │
└────────────────────────────┬─────────────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ Proyecto A │ │ Proyecto B │
│ (.venv A - Aislado)│ │ (.venv B - Aislado)│
│ - Pandas v1.0 │ │ - Pandas v2.0 │
│ - Requests │ │ - Gemini API │
└────────────────────┘ └────────────────────┘
의존성 오류 없이 작업 공간이 초기화되고 Python이 실행되도록 다음 순서를 엄격히 따르십시오.
- VS Code (
Ctrl + Shift + X)의 확장 탭에 액세스하십시오. - Microsoft에서 개발한 공식 Python 확장을 검색하십시오.
- 설치를 누르십시오. 이 확장은 편집기에서 디버깅, IntelliSense 및 동적 인터프리터 관리 기능을 활성화합니다.
단계 2: 글로벌 인터프리터 위치 확인 (사례 winget)
Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»winget 또는 Microsoft Store를 통해 Python을 설치할 때, 설치 프로그램이 시스템 표준 경로에 실행 파일을 등록하지 않는 경우가 흔합니다 (PATH). 기본 실행 파일을 확인하려면:
- 시스템의 명령 프롬프트(CMD 또는 PowerShell)를 열어 주십시오.
- 다음 검색 명령을 실행하십시오:
where.exe python- 터미널은 활성 실행 파일에 대한 절대 경로를 반환합니다. 예:
C:\Program Files\Python312\python.exe또는C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. 이 경로를 보관하십시오.
단계 3: 가상 환경 초기화 (.venv)
Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»VS Code의 내장 메뉴에서 오류나 차단되는 대화 상자가 나타나는 것을 방지하기 위해, 환경 생성을 편집기의 터미널에서 직접 수행하십시오:
- VS Code (
Ctrl + Ñ또는Ctrl + ~)에 내장된 터미널을 열어 주십시오. - 디렉토리 이름
.venv에 지정된 표준 가상 환경 모듈을 실행하십시오:
python -m venv .venv- 실행이 완료되면 작업 공간의 루트에 새 디렉토리
.venv가 생성됩니다.
단계 4: VS Code 인터프리터를 가상 환경과 연결합니다
Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»하위 디렉토리 .venv를 생성하는 것은 에디터에서 연결을 활성화하지 않습니다. VS Code가 새로 생성된 인터프리터를 사용하도록 강제해야 합니다:
- VS Code 에디터에서 확장자
.py를 가진 파일이 최소 하나 열려 있고 선택되어 있는지 확인하세요 (이것은 Python의 컨텍스트 엔진을 활성화합니다). Ctrl + Shift + P를 사용하여 명령어 팔레트를 열어주세요.- 입력하고
Python: Select Interpreter(Python: 인터프리터 선택)를 선택하세요. - 에디터가 목록을 표시합니다. 직접 해당 로컬 환경을 가리키는 옵션을 선택하세요. 일반적으로 추천되는 것으로 표시됩니다:
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe- 상태 확인: VS Code 상태 표시줄의 오른쪽 하단을 확인하세요.
- ✕ 잘못된 경로:
Python 3.x.x를 표시합니다 (시스템 전역 바이너리를 사용하고 있습니다). - ✓ 올바른 경로:
Python 3.x.x ('.venv')를 표시합니다 (환경이 올바르게 연결되어 있습니다).
- ✕ 잘못된 경로:
단계 5: 콘솔 활성화 및 종속성 설치
Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»에디터에서 인터프리터가 연결되면, 새로 열린 모든 터미널은 자동으로 활성 가상 환경을 상속합니다.
- 내장 터미널(
Ctrl + Ñ)을 열어주세요. - 명령 프롬프트가 왼쪽 끝에 활성화 접두사를 표시하는지 확인하세요:
(.venv) PS C:\MiProyecto>- 프로젝트의 필요한 라이브러리를 고립된 환경 내에서 직접 설치하세요:
pip install google-generativeai requests pandas3. 문제 해결 (Troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| 증상 | 근본 원인 | 해결책 |
|---|---|---|
내장 메뉴(Create Environment)가 수동으로 경로를 입력하도록 요청하고 프로그램이 중지됩니다. | VS Code는 시스템의 PATH에 있는 Python 기본 설치를 자동으로 찾지 못합니다 (일반적으로 winget를 통해 설치할 때). | 내장 대화 상자를 취소하세요. 이 가이드의 단계 3을 따라 python -m venv .venv를 사용하여 터미널을 통해 환경을 수동으로 생성하세요. |
‘Play’ 버튼을 누르면 오류 ModuleNotFoundError: No module named '<libreria>'가 발생합니다. | 코드는 설치된 패키지를 포함하는 인터프리터가 아닌 다른 인터프리터에서 실행되고 있습니다 (일반적으로 전역 인터프리터). | 1. VS Code의 하단 오른쪽 표시줄을 확인하여 ('.venv') 서브 인터프리터가 연결되어 있는지 확인하세요. 2. 그렇지 않다면, 단계 4를 반복하세요 ( Select Interpreter) |
터미널을 열 때 (.venv) 접두사를 표시하지 않습니다. | 현재 콘솔은 인터프리터를 설정한 후 업데이트되지 않았거나, PowerShell에서 실행 정책이 제한되어 있습니다. | 1. 하단 패널에 있는 쓰레기통 아이콘을 사용하여 모든 활성 터미널을 닫습니다. 2. Ctrl + Ñ을 사용하여 완전히 새로운 터미널을 엽니다. 활성화 스크립트가 자동으로 실행됩니다. |
| VS Code 상태 표시줄에 파이썬 버전 선택기가 표시되지 않습니다. | 편집기가 열린 코드 파일이 없기 때문에 파이썬의 컨텍스트 서비스를 로드하지 못했습니다. | 메이저 에디터에서 .py 확장 프로그램을 사용하여 어떤 파일이나 열어 Microsoft 확장 프로그램의 초기화를 강제합니다. |

