Configuración de Python y .venv en VS Code
Resolución de problemas de interpretación y entornos virtuales utilizando VS Code bajo sistemas Windows.
Esta guía proporciona el procedimiento técnico definitivo para diagnosticar, configurar e implementar entornos de desarrollo de Python en Visual Studio Code bajo sistemas Windows. Cubre desde la correcta asignación de intérpretes globales (incluyendo rutas no estándar de winget o Microsoft Store) hasta la automatización e instalación de dependencias en entornos aislados (.venv).
1. Fundamentos de Arquitectura
Sección titulada «1. Fundamentos de Arquitectura»Para asegurar un entorno de desarrollo predecible, es fundamental separar la interfaz de usuario del motor de ejecución y los paquetes de dependencias de cada proyecto.
El Intérprete vs. El Editor
Sección titulada «El Intérprete vs. El Editor»- Visual Studio Code (UI/Editor): Funciona estrictamente como un editor de texto avanzado y entorno integrado de desarrollo. No incluye un motor de Python integrado; en su lugar, delega la ejecución de código a un intérprete externo.
- Python Engine (
python.exe): Es el binario responsable de procesar e interpretar las instrucciones del código. Se ejecuta directamente sobre el sistema o dentro de subentornos.
Entorno Global vs. Entorno Virtual (.venv)
Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»- Python Global: Corresponde a la instalación base del sistema. Actúa como la plantilla inicial y no debe modificarse con paquetes externos para evitar colisiones de dependencias entre diferentes proyectos.
- Entornos Virtuales (
.venv): Son subdirectorios aislados que encapsulan su propio binario de Python y su árbol de dependencias (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. Procedimiento de Configuración Paso a Paso
Sección titulada «2. Procedimiento de Configuración Paso a Paso»Siga estrictamente el siguiente orden para asegurar que su espacio de trabajo inicialice y ejecute Python sin fallos de dependencias.
Paso 1: Instalación de la Extensión Oficial
Sección titulada «Paso 1: Instalación de la Extensión Oficial»- Acceda a la pestaña de Extensiones en VS Code (
Ctrl + Shift + X). - Busque la extensión oficial Python desarrollada por Microsoft.
- Presione Instalar. Esta extensión habilita las capacidades de depuración, IntelliSense y gestión dinámica de intérpretes en el editor.
Paso 2: Localización del Intérprete Global (Casos de winget)
Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»Cuando Python se instala a través de gestores de paquetes como winget o la Microsoft Store, es habitual que el instalador no registre el ejecutable en las rutas del sistema estándar (PATH). Para localizar su ejecutable base:
- Abra una terminal de comandos en su sistema (CMD o PowerShell).
- Ejecute el siguiente comando de búsqueda:
where.exe python- La terminal devolverá la ruta absoluta al ejecutable activo. Por ejemplo:
C:\Program Files\Python312\python.exeoC:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Conserve esta ruta.
Paso 3: Inicialización del Entorno Virtual (.venv)
Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»Para evitar fallos o ventanas de diálogo bloqueantes en los menús integrados de VS Code, realice la creación del entorno directamente desde la terminal del editor:
- Abra una terminal integrada en VS Code (
Ctrl + ÑoCtrl + ~). - Ejecute el módulo estándar de entorno virtual apuntando al nombre de directorio
.venv:
python -m venv .venv- Al finalizar la ejecución, se creará un nuevo directorio
.venven la raíz de su espacio de trabajo.
Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual
Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»Crear el subdirectorio .venv no activa la conexión en el editor. Debe forzar a VS Code a utilizar el intérprete recién creado:
- Asegúrese de tener al menos un archivo con extensión
.pyabierto y seleccionado en el editor de VS Code (esto activa el motor contextual de Python). - Abra la Paleta de Comandos utilizando
Ctrl + Shift + P. - Escriba y seleccione
Python: Select Interpreter(Python: Seleccionar Intérprete). - El editor presentará una lista. Seleccione la opción que apunte directamente a su entorno local. Generalmente se indica como recomendada:
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe- Verificación de Estado: Observe la esquina inferior derecha de la barra de estado de VS Code.
- ✕ Ruta Incorrecta: Muestra
Python 3.x.x(está utilizando el binario del sistema global). - ✓ Ruta Correcta: Muestra
Python 3.x.x ('.venv')(el entorno está correctamente enlazado).
- ✕ Ruta Incorrecta: Muestra
Paso 5: Activación de la Consola e Instalación de Dependencias
Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»Una vez enlazado el intérprete en el editor, cada nueva terminal abierta heredará automáticamente el entorno virtual activo.
- Abra una nueva terminal integrada (
Ctrl + Ñ). - Valide que el prompt de comandos muestre el prefijo de activación en el extremo izquierdo:
(.venv) PS C:\MiProyecto>- Instale las librerías necesarias del proyecto directamente dentro de su entorno aislado:
pip install google-generativeai requests pandas3. Resolución de Problemas (Troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| Síntoma | Causa Raíz | Solución |
|---|---|---|
El menú integrado Create Environment solicita ingresar una ruta manualmente y se congela. | VS Code no localiza de forma automática la instalación base de Python en el PATH del sistema (habitual en instalaciones vía winget). | Cancele el diálogo integrado. Siga el Paso 3 de esta guía para crear el entorno manualmente mediante terminal con python -m venv .venv. |
Error ModuleNotFoundError: No module named '<libreria>' al presionar ‘Play’. | El código está siendo ejecutado por un intérprete diferente al que contiene los paquetes instalados (generalmente el global). | 1. Verifique la barra inferior derecha de VS Code para confirmar que tiene enlazado el subintérprete ('.venv'). 2. Si no es así, repita el Paso 4 ( Select Interpreter). |
La terminal no muestra el prefijo (.venv) al abrirla. | La consola actual no se ha actualizado tras configurar el intérprete o tiene políticas de ejecución restringidas en PowerShell. | 1. Cierre todas las terminales activas con el icono del cubo de basura en el panel inferior. 2. Abra una terminal completamente nueva ( Ctrl + Ñ). El script de activación se ejecutará de forma automática. |
| No aparece el selector de versión de Python en la barra de estado de VS Code. | El editor no ha cargado los servicios contextuales de Python porque no hay archivos de código abiertos. | Abra cualquier archivo con extensión .py en su editor principal para forzar la inicialización de la extensión de Microsoft. |

