Configurazione di Python e .venv in VS Code
Risoluzione dei problemi di interpretazione e degli ambienti virtuali utilizzando VS Code su sistemi Windows.
Questa guida fornisce la procedura tecnica definitiva per diagnosticare, configurare e implementare ambienti di sviluppo Python in Visual Studio Code su sistemi Windows. Copre dalla corretta assegnazione degli interpreti globali (inclusi i percorsi non standard di winget o Microsoft Store) fino all'automazione e all'installazione delle dipendenze in ambienti isolati (.venv).
1. Fondamenti di Architettura
Sección titulada «1. Fundamentos de Arquitectura»Per garantire un ambiente di sviluppo prevedibile, è fondamentale separare l'interfaccia utente dal motore di esecuzione e dai pacchetti di dipendenze di ogni progetto.
L'Interprete vs. L'Editor
Sección titulada «El Intérprete vs. El Editor»- Visual Studio Code (UI/Editor): Funziona strettamente come un editor di testo avanzato e un ambiente di sviluppo integrato. Non include un motore Python integrato; invece, delega l'esecuzione del codice a un interprete esterno.
- Python Engine (
python.exe): È il binario responsabile dell'elaborazione e dell'interpretazione delle istruzioni del codice. Viene eseguito direttamente sul sistema o all'interno di sotto-ambienti.
Ambiente Globale vs. Ambiente Virtuale (.venv)
Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»- Python Globale: Corrisponde all'installazione di base del sistema. Funge da modello iniziale e non deve essere modificata con pacchetti esterni per evitare conflitti di dipendenze tra diversi progetti.
- Ambienti Virtuali (
.venv): Sono sottodirectory isolate che incapsulano il proprio binario Python e il proprio albero di dipendenze (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 di Configurazione Passo dopo Passo
Sección titulada «2. Procedimiento de Configuración Paso a Paso»Seguire rigorosamente il seguente ordine per assicurarsi che lo spazio di lavoro inizializzi ed esegua Python senza errori di dipendenze.
Passo 1: Installazione dell'Estensione Ufficiale
Sección titulada «Paso 1: Instalación de la Extensión Oficial»- Accedi alla scheda Estensioni in VS Code (
Ctrl + Shift + X). - Cerca l'estensione ufficiale Python sviluppata da Microsoft.
- Premi Installa. Questa estensione abilita le capacità di debugging, IntelliSense e la gestione dinamica degli interpreti nell'editor.
Passo 2: Localizzazione dell'interprete globale (Casi di winget)
Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»Quando Python viene installato tramite gestori di pacchetti come winget o il Microsoft Store, è comune che l'installatore non registri l'eseguibile nei percorsi di sistema standard (PATH). Per localizzare il suo eseguibile base:
- Aprire un terminale dei comandi nel sistema (CMD o PowerShell).
- Eseguire il seguente comando di ricerca:
where.exe python- Il terminale restituirà il percorso assoluto dell'eseguibile attivo. Ad esempio:
C:\Program Files\Python312\python.exeoC:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Conservare questo percorso.
Passaggio 3: Inizializzazione dell'ambiente virtuale (.venv)
Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»Per evitare errori o finestre di dialogo bloccanti nei menu integrati di VS Code, eseguire la creazione dell'ambiente direttamente dal terminale dell'editor:
- Apri un terminale integrato in VS Code (
Ctrl + ÑoCtrl + ~). - Esegui il modulo standard dell'ambiente virtuale puntando al nome della directory
.venv:
python -m venv .venv- Al termine dell'esecuzione, verrà creata una nuova directory
.venvnella radice del tuo spazio di lavoro.
Passaggio 4: Collegamento dell'interprete di VS Code con l'ambiente virtuale
Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»Creare la sottodirectory .venv non attiva la connessione nell'editor. È necessario forzare VS Code a utilizzare l'interprete appena creato:
- Assicurati di avere almeno un file con estensione
.pyaperto e selezionato nell'editor di VS Code (questo attiva il motore contestuale di Python). - Apri la Palette dei comandi utilizzando
Ctrl + Shift + P. - Scrivi e seleziona
Python: Select Interpreter(Python: Seleziona interprete). - L'editor presenterà un elenco. Seleziona l'opzione che punta direttamente al tuo ambiente locale. Generalmente è indicata come consigliata:
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe- Verifica dello Stato: Osservare l'angolo inferiore destro della barra di stato di VS Code.
- ✕ Percorso Errato: Mostra
Python 3.x.x(sta utilizzando il binario del sistema globale). - ✓ Chemin Correct: Mostra
Python 3.x.x ('.venv')(l'ambiente è correttamente collegato).
- ✕ Percorso Errato: Mostra
Passaggio 5: Attivazione della console e installazione delle dipendenze
Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»Una volta collegato l'interprete nell'editor, ogni nuovo terminale aperto erediterà automaticamente l'ambiente virtuale attivo.
- Apri un nuovo terminale integrato ([[PC_BLOCK_0]).
- Verifica che il prompt dei comandi mostri il prefisso di attivazione all'estrema sinistra:
(.venv) PS C:\MiProyecto>- Installa le librerie necessarie del progetto direttamente all'interno del tuo ambiente isolato:
pip install google-generativeai requests pandas3. Risoluzione dei problemi (Troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| Sintomo | Causa principale | Soluzione |
|---|---|---|
Il menu integrato Create Environment richiede l'inserimento manuale di un percorso e si blocca. | VS Code non individua automaticamente l'installazione base di Python nel PATH del sistema (comune nelle installazioni tramite winget). | Annullare la finestra di dialogo integrata. Seguire il Passo 3 di questa guida per creare l'ambiente manualmente utilizzando il terminale con python -m venv .venv. |
Errore ModuleNotFoundError: No module named '<libreria>' quando si preiona 'Play'. | Il codice viene eseguito da un interprete diverso da quello che contiene i pacchetti installati (generalmente quello globale). | 1. Verificare la barra inferiore destra di VS Code per confermare di avere collegato il subinterprete ('.venv'). 2. Se non è così, ripetere il Passo 4 ( Select Interpreter). |
Il terminale non mostra il prefisso (.venv) all'apertura. | La console attuale non è stata aggiornata dopo la configurazione dell'interprete o ha criteri di esecuzione limitati in PowerShell. | 1. Chiudi tutte le terminali attive con l'icona del cestino nel pannello inferiore. 2. Apri una terminale completamente nuova ( Ctrl + Ñ). Lo script di attivazione verrà eseguito automaticamente. |
| Il selettore della versione di Python non appare nella barra di stato di VS Code. | L'editor non ha caricato i servizi contestuali di Python perché non ci sono file di codice aperti. | Apri qualsiasi file con estensione .py nel tuo editor principale per forzare l'inizializzazione dell'estensione Microsoft. |

