Configuració de Python i .venv en VS Code
Resolució de problemes d'interpretació i entorns virtuals utilitzant VS Code en sistemes Windows.
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).
1. Fundaments d'Arquitectura
Sección titulada «1. Fundamentos de Arquitectura»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.
L'intèrpret vs. l'editor
Sección titulada «El Intérprete vs. El Editor»- 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.
Entorn global vs. entorn virtual (.venv)
Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»- 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 │
└────────────────────┘ └────────────────────┘
2. Procediment de configuració pas a pas
Sección titulada «2. Procedimiento de Configuración Paso a Paso»Seguiu estrictament l'ordre següent per assegurar que l'espai de treball s'inicialitzi i executi Python sense errors de dependències.
Pas 1: Instal·lació de l'extensió oficial
Sección titulada «Paso 1: Instalación de la Extensión Oficial»- Accediu a la pestanya de Extensions en VS Code (
Ctrl + Shift + X). - Busqueu l'extensió oficial Python desenvolupada per Microsoft.
- 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:
- Obreu una terminal de comandes al vostre sistema (CMD o PowerShell).
- Executeu el següent comandament de cerca:
where.exe python- La terminal retornarà la ruta absoluta de l'executable actiu. Per exemple:
C:\Program Files\Python312\python.exeoC:\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:
- Obriu una terminal integrada a VS Code (
Ctrl + ÑoCtrl + ~). - Executeu el mòdul estàndard d'entorn virtual apuntant al nom de directori
.venv:
python -m venv .venv- En finalitzar l'execució, es crearà un nou directori
.venva 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:
- Assegureu-vos de tenir almenys un fitxer amb extensió
.pyobert i seleccionat a l'editor de VS Code (això activa el motor contextual de Python). - Obriu la Paleta de Comandes utilitzant
Ctrl + Shift + P. - Escriviu i seleccioneu
Python: Select Interpreter(Python: Seleccionar Intèrpret). - L'editor presentarà una llista. Seleccioneu l'opció que apunta directament al vostre entorn local. Generalment s'indica com a recomanada:
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe- 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).
- ✕ Ruta incorrecta: Mostra
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.
- Obri una nova terminal integrada (
Ctrl + Ñ). - Valida que el prompt de comandes mostri el prefixe d'activació a l'extrem esquerre:
(.venv) PS C:\MiProyecto>- Installa les biblioteques necessàries del projecte directament dins del seu entorn aïllat:
pip install google-generativeai requests pandas3. Resolució de Problemes (Troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| Símptoma | Causa 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. |

