Ir al contenido

Konfiguracja Pythona i .venv w VS Code

Rozwiązywanie problemów z interpretacją i środowiskami wirtualnymi przy użyciu VS Code w systemach Windows.

0odwiedzin

Niniejszy przewodnik dostarcza ostateczną procedurę techniczną do diagnozowania, konfigurowania i wdrażania środowisk programistycznych Pythona w Visual Studio Code w systemach Windows. Obejmuje wszystko, od prawidłowego przypisywania interpreterów globalnych (w tym niestandardowych ścieżek winget lub Microsoft Store) do automatyzacji i instalacji zależności w izolowanych środowiskach (.venv).


Aby zapewnić przewidywalne środowisko programistyczne, konieczne jest oddzielenie interfejsu użytkownika od silnika wykonawczego i pakietów zależności każdego projektu.

  • Visual Studio Code (UI/Edytor): Działa ściśle jako zaawansowany edytor tekstu i zintegrowane środowisko programistyczne. Nie zawiera wbudowanego silnika Python; zamiast tego, deleguje wykonanie kodu do zewnętrznego interpretera.
  • Silnik Python (python.exe): Jest to plik wykonywalny odpowiedzialny za przetwarzanie i interpretowanie instrukcji kodu. Wykonuje się bezpośrednio na systemie lub wewnątrz podśrodowisk.

Środowisko globalne vs. środowisko wirtualne (.venv)

Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»
  • Python Globalny: Odnosi się do podstawowej instalacji systemu. Działa jako początkowa szablon i nie powinien być modyfikowany za pomocą zewnętrznych pakietów, aby uniknąć kolizji zależności między różnymi projektami.
  • Środowiska wirtualne (.venv): Są to izolowane podkatalogi, które zawierają własny plik wykonywalny Pythona i drzewo zależności (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      │
   └────────────────────┘        └────────────────────┘

Postępuj ściśle według następującej kolejności, aby zapewnić, że środowisko robocze inicjalizuje i wykonuje Python bez błędów zależności.

  1. Przejdź do zakładki Rozszerzenia w VS Code (Ctrl + Shift + X).
  2. Wyszukaj oficjalną rozszerzenie Python opracowaną przez Microsoft.
  3. Naciśnij Zainstaluj. To rozszerzenie umożliwia debugowanie, IntelliSense oraz dynamiczne zarządzanie interpreterami w edytorze.

Krok 2: Lokalizacja Globalnego Interpretera (Przypadki winget)

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

Gdy Python jest instalowany za pomocą menedżerów pakietów, takich jak winget lub Sklep Microsoft, zwykle instalator nie rejestruje pliku wykonywalnego w standardowych ścieżkach systemu (PATH). Aby znaleźć podstawowy plik wykonywalny:

  1. Otwórz terminal poleceń w systemie (CMD lub PowerShell).
  2. Wykonaj następujące polecenie wyszukiwania:
Ventana de terminal
where.exe python
  1. Terminal zwróci ścieżkę bezwzględną do aktywnego programu. Na przykład: C:\Program Files\Python312\python.exe lub C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Zachowaj tę ścieżkę.

Krok 3: Inicjacja Środowiska Wirtualnego (.venv)

Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»

Aby uniknąć błędów lub okien dialogowych blokujących w menu zintegrowanym VS Code, utwórz środowisko bezpośrednio z terminala edytora:

  1. Otwórz zintegrowany terminal w VS Code (Ctrl + Ñ lub Ctrl + ~).
  2. Uruchom standardowy moduł środowiska wirtualnego, wskazując na nazwę katalogu .venv:
Ventana de terminal
python -m venv .venv
  1. Po zakończeniu wykonywania, zostanie utworzony nowy katalog .venv w głównym katalogu Twojej przestrzeni roboczej.

Krok 4: Połączenie interpretera VS Code ze środowiskiem wirtualnym

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

Utworzenie podkatalogu .venv nie aktywuje połączenia w edytorze. Należy zmusić VS Code do użycia nowo utworzonego interpretera:

  1. Upewnij się, że masz co najmniej jeden plik z rozszerzeniem .py otwarty i wybrany w edytorze VS Code (to aktywuje silnik kontekstowy Pythonu).
  2. Otwórz Paletę poleceń za pomocą Ctrl + Shift + P.
  3. Wpisz i wybierz Python: Select Interpreter (Python: Wybór interpretera).
  4. Edytor przedstawi listę. Wybierz opcję, która wskazuje bezpośrednio na środowisko lokalne. Zwykle jest oznaczona jako zalecana:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. Weryfikacja stanu: Obserwuj prawy dolny róg paska stanu VS Code.
    • ✕ Nieprawidłowa ścieżka: Wyświetla Python 3.x.x (używasz binariów systemu globalnego).
    • ✓ Prawidłowa ścieżka: Wyświetla Python 3.x.x ('.venv') (środowisko jest poprawnie połączone).

Po połączeniu interpretera w edytorze, każde nowe otwarte terminalne będzie automatycznie dziedziczyć aktywne środowisko wirtualne.

  1. Otwórz nową terminal zintegrowaną (Ctrl + Ñ).
  2. Sprawdź, czy podpowiedź polecenia wyświetla prefiks aktywacji po lewej stronie:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Zainstaluj niezbędne biblioteki projektu bezpośrednio w izolowanym środowisku:
Ventana de terminal
pip install google-generativeai requests pandas

3. Rozwiązywanie problemów (troubleshooting)

Sección titulada «3. Resolución de Problemas (Troubleshooting)»
ObjawPrzyczyna podstawowaRozwiązanie
Wbudowane menu Create Environment prosi o ręczne wprowadzenie ścieżki i zamarza.VS Code nie lokalizuje automatycznie podstawowej instalacji Pythona w PATH systemu (często występuje w instalacjach za pośrednictwem winget).Anuluj wbudowany dialog. Postępuj zgodnie z krok 3 tej instrukcji, aby utworzyć środowisko ręcznie za pomocą terminala z python -m venv .venv.
Błąd ModuleNotFoundError: No module named '<libreria>' podczas naciskania 'Play'.Kod jest wykonywany przez inny interpreter niż ten, który zawiera zainstalowane pakiety (zwykle globalny).1. Sprawdź dolny prawy róg VS Code, aby potwierdzić, że masz połączony podinterpretator ('.venv').
2. Jeśli nie, powtórz krok 4 (Select Interpreter).
Terminal nie wyświetla prefiksu (.venv) po otwarciu.Aktualna konsola nie została zaktualizowana po skonfigurowaniu interpretera lub ma ograniczone zasady wykonywania w PowerShell.1. Zamknij wszystkie aktywne terminale z ikoną kosza na dolnym panelu.
2. Otwórz całkowicie nowy terminal (Ctrl + Ñ). Skrypt aktywacyjny zostanie uruchomiony automatycznie.
Nie pojawia się wybór wersji Pythona na pasku stanu VS Code.Edytor nie załadował usług kontekstowych Pythona, ponieważ nie ma otwartych plików kodu.Otwórz dowolny plik z rozszerzeniem .py w swoim głównym edytorze, aby wymusić inicjowanie rozszerzenia Microsoft.