Configuração de Python e .venv no VS Code
Resolução de problemas de interpretação e ambientes virtuais utilizando VS Code em sistemas Windows.
Esta guia fornece o procedimento técnico definitivo para diagnosticar, configurar e implementar ambientes de desenvolvimento de Python em Visual Studio Code sob sistemas Windows.
1. Fundamentos de Arquitetura
Sección titulada «1. Fundamentos de Arquitectura»Para garantir um ambiente de desenvolvimento previsível, é fundamental separar a interface de usuário do motor de execução e os pacotes de dependências de cada projeto.
O Interpretador vs. O Editor
Sección titulada «El Intérprete vs. El Editor»- Visual Studio Code (UI/Editor): Funciona estrictamente como um editor de texto avançado e ambiente integrado de desenvolvimento. Não inclui um motor de Python integrado; em seu lugar, delega a execução de código a um intérprete externo.
- Python Engine (
python.exe): É o binário responsável por processar e interpretar as instruções do código. Se executa diretamente sobre o sistema ou dentro de subambientes.
Ambiente Global vs. Ambiente Virtual (.venv)
Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»)- Python Global: Corresponde à instalação base do sistema. Actua como a plantilla inicial e não deve ser modificada com pacotes externos para evitar colisões de dependências entre diferentes projetos.
- Ambientes Virtuais (
.venv): São subdirectorios isolados que encapsulam seu próprio binário de Python e seu árvore de dependências (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. Procedimento de Configuração Passo a Passo
Sección titulada «2. Procedimiento de Configuración Paso a Paso»Siga estritamente a seguinte ordem para garantir que seu espaço de trabalho inicialize e execute o Python sem falhas de dependências.
Passo 1: Instalação da Extensão Oficial
Sección titulada «Paso 1: Instalación de la Extensión Oficial»- Acesse a pestaña de Extensiones em VS Code (
Ctrl + Shift + X). - Procure a extensão oficial Python desenvolvida por Microsoft.
- Pressione Instalar. Essa extensão habilita as capacidades de depuração, IntelliSense e gestão dinâmica de intérpretes no editor.
Paso 2: Localização do Intérprete Global (Caso de winget)
Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»)Quando Python é instalado a partir de gestores de paquetes como winget ou a Microsoft Store, é comum que o instalador não registre o executável na rota do sistema padrão (PATH).
- Abra um terminal de comandos no seu sistema (CMD ou PowerShell).
- Execute o seguinte comando de busca:
where.exe python- O terminal retornará o caminho absoluto ao executável ativo. Por exemplo:\r\n
C:\Program Files\Python312\python.exeouC:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Mantenha este caminho.
Paso 3: Inicialização do Ambiente Virtual (.venv)
Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»)Para evitar falhas ou janelas de diálogo bloqueantes nos menus integrados do VS Code, realize a criação do ambiente diretamente do terminal do editor:
- Abra uma terminal integrada em VS Code (
Ctrl + ÑouCtrl + ~). - Execute o módulo estándar de ambiente virtual apontando para o nome do diretório
.venv:
python -m venv .venv- Al finalizar la ejecución, se creará un nuevo directorio .venv en la raíz de su espacio de trabajo.
Passo 4: Vinculação do Interpretador do VS Code com o Ambiente 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 .py abierto 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).
- O editor apresentará uma lista. Selecione a opção que aponte diretamente para o seu ambiente local. Geralmente é indicada 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).
Passo 5: Ativação do Console e Instalação de Dependências
Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»Uma vez vinculado o interpretador no editor, cada novo terminal aberto herdará automaticamente o ambiente virtual ativo.
- Abra una nueva terminal integrada (Ctrl + Ñ).
- Valide se o prompt de comando mostra o prefixo de ativação na extremidade esquerda:
(.venv) PS C:\MiProyecto>- Instale as bibliotecas necessárias do projeto diretamente dentro do seu ambiente isolado:
pip install google-generativeai requests pandas3. Resolução de Problemas (Troubleshooting)
Sección titulada «3. Resolución de Problemas (Troubleshooting)»| Sintoma | Causa Raiz | Solução |
|---|---|---|
| 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 o diálogo integrado. Siga o Passo 3 desta guia para criar o ambiente manualmente mediante terminal com python -m venv .venv. |
Erro ModuleNotFoundError: No module named '<libreria>' ao pressionar ‘Play’. | O código está sendo executado por um interpretador diferente do que contém os pacotes instalados (geralmente o 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. | O console atual não foi atualizado após configurar o interpretador ou possui políticas de execução restritas no 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. | O editor não carregou os serviços contextuais do Python porque não há arquivos de código abertos. | Abra qualquer arquivo com extensão .py em seu editor principal para forçar a inicialização da extensão de Microsoft. |

