Ir al contenido

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): 코드 지시문을 처리하고 해석하는 데 책임이 있는 바이너리입니다. 시스템에서 직접 실행되거나 하위 환경 내에서 실행됩니다.
  • 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이 실행되도록 다음 순서를 엄격히 따르십시오.

  1. VS Code (Ctrl + Shift + X)의 확장 탭에 액세스하십시오.
  2. Microsoft에서 개발한 공식 Python 확장을 검색하십시오.
  3. 설치를 누르십시오. 이 확장은 편집기에서 디버깅, IntelliSense 및 동적 인터프리터 관리 기능을 활성화합니다.

단계 2: 글로벌 인터프리터 위치 확인 (사례 winget)

Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»

winget 또는 Microsoft Store를 통해 Python을 설치할 때, 설치 프로그램이 시스템 표준 경로에 실행 파일을 등록하지 않는 경우가 흔합니다 (PATH). 기본 실행 파일을 확인하려면:

  1. 시스템의 명령 프롬프트(CMD 또는 PowerShell)를 열어 주십시오.
  2. 다음 검색 명령을 실행하십시오:
Ventana de terminal
where.exe python
  1. 터미널은 활성 실행 파일에 대한 절대 경로를 반환합니다. 예: C:\Program Files\Python312\python.exe 또는 C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. 이 경로를 보관하십시오.

VS Code의 내장 메뉴에서 오류나 차단되는 대화 상자가 나타나는 것을 방지하기 위해, 환경 생성을 편집기의 터미널에서 직접 수행하십시오:

  1. VS Code (Ctrl + Ñ 또는 Ctrl + ~)에 내장된 터미널을 열어 주십시오.
  2. 디렉토리 이름 .venv에 지정된 표준 가상 환경 모듈을 실행하십시오:
Ventana de terminal
python -m venv .venv
  1. 실행이 완료되면 작업 공간의 루트에 새 디렉토리 .venv가 생성됩니다.

단계 4: VS Code 인터프리터를 가상 환경과 연결합니다

Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»

하위 디렉토리 .venv를 생성하는 것은 에디터에서 연결을 활성화하지 않습니다. VS Code가 새로 생성된 인터프리터를 사용하도록 강제해야 합니다:

  1. VS Code 에디터에서 확장자 .py를 가진 파일이 최소 하나 열려 있고 선택되어 있는지 확인하세요 (이것은 Python의 컨텍스트 엔진을 활성화합니다).
  2. Ctrl + Shift + P를 사용하여 명령어 팔레트를 열어주세요.
  3. 입력하고 Python: Select Interpreter (Python: 인터프리터 선택)를 선택하세요.
  4. 에디터가 목록을 표시합니다. 직접 해당 로컬 환경을 가리키는 옵션을 선택하세요. 일반적으로 추천되는 것으로 표시됩니다:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. 상태 확인: VS Code 상태 표시줄의 오른쪽 하단을 확인하세요.
    • ✕ 잘못된 경로: Python 3.x.x를 표시합니다 (시스템 전역 바이너리를 사용하고 있습니다).
    • ✓ 올바른 경로: Python 3.x.x ('.venv')를 표시합니다 (환경이 올바르게 연결되어 있습니다).

에디터에서 인터프리터가 연결되면, 새로 열린 모든 터미널은 자동으로 활성 가상 환경을 상속합니다.

  1. 내장 터미널(Ctrl + Ñ)을 열어주세요.
  2. 명령 프롬프트가 왼쪽 끝에 활성화 접두사를 표시하는지 확인하세요:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. 프로젝트의 필요한 라이브러리를 고립된 환경 내에서 직접 설치하세요:
Ventana de terminal
pip install google-generativeai requests pandas

증상근본 원인해결책
내장 메뉴(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 확장 프로그램의 초기화를 강제합니다.