Konfiguracja Pythona i .venv w VS Code
Rozwiązywanie problemów z interpretacją i środowiskami wirtualnymi przy użyciu VS Code w systemach Windows.
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).
1. Podstawy architektury
Sección titulada «1. Fundamentos de Arquitectura»Aby zapewnić przewidywalne środowisko programistyczne, konieczne jest oddzielenie interfejsu użytkownika od silnika wykonawczego i pakietów zależności każdego projektu.
Interpreter vs. Edytor
Sección titulada «El Intérprete vs. El Editor»- 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 │
└────────────────────┘ └────────────────────┘
2. Procedura konfiguracji krok po kroku
Sección titulada «2. Procedimiento de Configuración Paso a Paso»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.
Krok 1: Instalacja oficjalnego rozszerzenia
Sección titulada «Paso 1: Instalación de la Extensión Oficial»- Przejdź do zakładki Rozszerzenia w VS Code (
Ctrl + Shift + X). - Wyszukaj oficjalną rozszerzenie Python opracowaną przez Microsoft.
- 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:
- Otwórz terminal poleceń w systemie (CMD lub PowerShell).
- Wykonaj następujące polecenie wyszukiwania:
where.exe python- Terminal zwróci ścieżkę bezwzględną do aktywnego programu. Na przykład:
C:\Program Files\Python312\python.exelubC:\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:
- Otwórz zintegrowany terminal w VS Code (
Ctrl + ÑlubCtrl + ~). - Uruchom standardowy moduł środowiska wirtualnego, wskazując na nazwę katalogu
.venv:
python -m venv .venv- Po zakończeniu wykonywania, zostanie utworzony nowy katalog
.venvw 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:
- Upewnij się, że masz co najmniej jeden plik z rozszerzeniem
.pyotwarty i wybrany w edytorze VS Code (to aktywuje silnik kontekstowy Pythonu). - Otwórz Paletę poleceń za pomocą
Ctrl + Shift + P. - Wpisz i wybierz
Python: Select Interpreter(Python: Wybór interpretera). - Edytor przedstawi listę. Wybierz opcję, która wskazuje bezpośrednio na środowisko lokalne. Zwykle jest oznaczona jako zalecana:
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe- 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).
- ✕ Nieprawidłowa ścieżka: Wyświetla
Krok 5: Aktywacja konsoli i instalacja zależności
Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»Po połączeniu interpretera w edytorze, każde nowe otwarte terminalne będzie automatycznie dziedziczyć aktywne środowisko wirtualne.
- Otwórz nową terminal zintegrowaną (
Ctrl + Ñ). - Sprawdź, czy podpowiedź polecenia wyświetla prefiks aktywacji po lewej stronie:
(.venv) PS C:\MiProyecto>- Zainstaluj niezbędne biblioteki projektu bezpośrednio w izolowanym środowisku:
pip install google-generativeai requests pandas3. Rozwiązywanie problemów (troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| Objaw | Przyczyna podstawowa | Rozwią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. |

