Ir al contenido

Configuració de Python i .venv en VS Code

Resolució de problemes d'interpretació i entorns virtuals utilitzant VS Code en sistemes Windows.

0lectures

Aquesta guia proporciona el procediment tècnic definitiu per diagnosticar, configurar i implementar entorns de desenvolupament de Python en Visual Studio Code en sistemes Windows. Cobre des de l'assignació correcta d'intèrprets globals (incloent rutes no estàndard de winget o Microsoft Store) fins a l'automatització i instal·lació de dependències en entorns aïllats (.venv).


Per assegurar un entorn de desenvolupament predecible, és fonamental separar la interfície d'usuari del motor d'execució i els paquets de dependències de cada projecte.

  • Visual Studio Code (UI/Editor): Funciona estrictament com un editor de text avançat i entorn integrat de desenvolupament. No inclou un motor de Python integrat; en comptes d'això, delega l'execució de codi a un intèrpret extern.
  • Python Engine (python.exe): És el binari responsable de processar i interpretar les instruccions del codi. S'executa directament sobre el sistema o dins de subentorns.
  • Python global: Correspon a la instal·lació base del sistema. Actua com a la plantilla inicial i no s'ha de modificar amb paquets externs per evitar col·lisions de dependències entre diferents projectes.
  • Entorns virtuals (.venv): Són subdirectoris aïllats que encapsulen el seu propi binari de Python i el seu arbre de dependències (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      │
   └────────────────────┘        └────────────────────┘

Seguiu estrictament l'ordre següent per assegurar que l'espai de treball s'inicialitzi i executi Python sense errors de dependències.

  1. Accediu a la pestanya de Extensions en VS Code (Ctrl + Shift + X).
  2. Busqueu l'extensió oficial Python desenvolupada per Microsoft.
  3. Premeu Instalar. Aquesta extensió habilita les capacitats de depuració, IntelliSense i la gestió dinàmica d'intèrprets en l'editor.

Pas 2: Localització de l'intèrpret global (casos de winget)

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

Quan Python s'instal·la a través de gestors de paquets com winget o la Microsoft Store, és habitual que l'instal·lador no registri l'executable en les rutes del sistema estàndard (PATH). Per localitzar el seu executable base:

  1. Obreu una terminal de comandes al vostre sistema (CMD o PowerShell).
  2. Executeu el següent comandament de cerca:
Ventana de terminal
where.exe python
  1. La terminal retornarà la ruta absoluta de l'executable actiu. Per exemple: C:\Program Files\Python312\python.exe o C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Conserva aquesta ruta.

Pas 3: Inicialització de l'entorn virtual (.venv)

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

Per evitar errors o finestres de diàleg bloquejants als menús integrats de VS Code, realitzeu la creació de l'entorn directament des de la terminal de l'editor:

  1. Obriu una terminal integrada a VS Code (Ctrl + Ñ o Ctrl + ~).
  2. Executeu el mòdul estàndard d'entorn virtual apuntant al nom de directori .venv:
Ventana de terminal
python -m venv .venv
  1. En finalitzar l'execució, es crearà un nou directori .venv a la raïx de l'espai de treball.

Pas 4: Vinculació de l'intèrpret de VS Code amb l'entorn virtual

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

Crear el subdirrectori .venv no activa la connexió a l'editor. Cal forçar VS Code a utilitzar l'intèrpret acabada de crear:

  1. Assegureu-vos de tenir almenys un fitxer amb extensió .py obert i seleccionat a l'editor de VS Code (això activa el motor contextual de Python).
  2. Obriu la Paleta de Comandes utilitzant Ctrl + Shift + P.
  3. Escriviu i seleccioneu Python: Select Interpreter (Python: Seleccionar Intèrpret).
  4. L'editor presentarà una llista. Seleccioneu l'opció que apunta directament al vostre entorn local. Generalment s'indica com a recomanada:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. Verificació d'Estat: Observa la cantonada inferior dreta de la barra d'estat de VS Code.
    • ✕ Ruta incorrecta: Mostra Python 3.x.x (està utilitzant el binari del sistema global).
    • ✓ Ruta Correcta: Mostra Python 3.x.x ('.venv') (l'entorn està correctament enllaçat).

Pas 5: Activació de la Consola i Instal·lació de Dependències

Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»

Un cop enllaçat l'intèrpret en l'editor, cada nova terminal oberta heredarà automàticament l'entorn virtual actiu.

  1. Obri una nova terminal integrada (Ctrl + Ñ).
  2. Valida que el prompt de comandes mostri el prefixe d'activació a l'extrem esquerre:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Installa les biblioteques necessàries del projecte directament dins del seu entorn aïllat:
Ventana de terminal
pip install google-generativeai requests pandas

SímptomaCausa RaïçSolució
El menú integrat Create Environment demana introduir una ruta manualment i es congela.VS Code no localitza de forma automàtica la instal·lació base de Python en el PATH del sistema (habitual en instal·lacions via winget).Cancella el diàleg integrat. Segueix el Pas 3 d'aquesta guia per crear l'entorn manualment mitjançant la terminal amb python -m venv .venv.
Error ModuleNotFoundError: No module named '<libreria>' en prémer 'Play'.El cod està sent executat per un intèrpret diferent de l'que conté els paquets instal·lats (generalment el global).1. Verifiqueu la barra inferior dreta de VS Code per confirmar que teniu enllaçat el subintèrprete ('.venv').
2. Si no és així, repeteu el Pas 4 (Select Interpreter).
La terminal no mostra el prefixe (.venv) en obrir-la.La consola actual no s'ha actualitzat després de configurar l'intèrprete o té polítiques d'execució restringides a PowerShell.1. Teniu tancades totes les terminals actives amb la icona de la paperera al panell inferior.
2. Obriu una terminal completament nova (Ctrl + Ñ). El script d'activació s'executarà de forma automàtica.
No apareix el selector de versió de Python a la barra d'estat de VS Code.L'editor no ha carregat els serveis contextuals de Python perquè no hi ha cap arxiu de codi obert.Obreu qualsevol arxiu amb extensió .py al vostre editor principal per forçar la inicialització de l'extensió de Microsoft.