Ir al contenido

Configurazione di Python e .venv in VS Code

Risoluzione dei problemi di interpretazione e degli ambienti virtuali utilizzando VS Code su sistemi Windows.

0letture

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).


Per garantire un ambiente di sviluppo prevedibile, è fondamentale separare l'interfaccia utente dal motore di esecuzione e dai pacchetti di dipendenze di ogni progetto.

  • 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»
  1. Accedi alla scheda Estensioni in VS Code (Ctrl + Shift + X).
  2. Cerca l'estensione ufficiale Python sviluppata da Microsoft.
  3. 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:

  1. Aprire un terminale dei comandi nel sistema (CMD o PowerShell).
  2. Eseguire il seguente comando di ricerca:
Ventana de terminal
where.exe python
  1. Il terminale restituirà il percorso assoluto dell'eseguibile attivo. Ad esempio: C:\Program Files\Python312\python.exe o C:\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:

  1. Apri un terminale integrato in VS Code (Ctrl + Ñ o Ctrl + ~).
  2. Esegui il modulo standard dell'ambiente virtuale puntando al nome della directory .venv:
Ventana de terminal
python -m venv .venv
  1. Al termine dell'esecuzione, verrà creata una nuova directory .venv nella 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:

  1. Assicurati di avere almeno un file con estensione .py aperto e selezionato nell'editor di VS Code (questo attiva il motore contestuale di Python).
  2. Apri la Palette dei comandi utilizzando Ctrl + Shift + P.
  3. Scrivi e seleziona Python: Select Interpreter (Python: Seleziona interprete).
  4. L'editor presenterà un elenco. Seleziona l'opzione che punta direttamente al tuo ambiente locale. Generalmente è indicata come consigliata:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. 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).

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.

  1. Apri un nuovo terminale integrato ([[PC_BLOCK_0]).
  2. Verifica che il prompt dei comandi mostri il prefisso di attivazione all'estrema sinistra:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Installa le librerie necessarie del progetto direttamente all'interno del tuo ambiente isolato:
Ventana de terminal
pip install google-generativeai requests pandas

3. Risoluzione dei problemi (Troubleshooting)

Sección titulada «3. Resolución de Problemas (Troubleshooting)»
SintomoCausa principaleSoluzione
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.