Ir al contenido

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.

0lecturas

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.


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.

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

  1. Acesse a pestaña de Extensiones em VS Code (Ctrl + Shift + X).
  2. Procure a extensão oficial Python desenvolvida por Microsoft.
  3. 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).

  1. Abra um terminal de comandos no seu sistema (CMD ou PowerShell).
  2. Execute o seguinte comando de busca:
Ventana de terminal
where.exe python
  1. O terminal retornará o caminho absoluto ao executável ativo. Por exemplo:\r\nC:\Program Files\Python312\python.exe ou C:\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:

  1. Abra uma terminal integrada em VS Code (Ctrl + Ñ ou Ctrl + ~).
  2. Execute o módulo estándar de ambiente virtual apontando para o nome do diretório .venv:
Ventana de terminal
python -m venv .venv
  1. 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:

  1. 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).
  2. Abra la Paleta de Comandos utilizando Ctrl + Shift + P.
  3. Escriba y seleccione Python: Select Interpreter (Python: Seleccionar Intérprete).
  4. O editor apresentará uma lista. Selecione a opção que aponte diretamente para o seu ambiente local. Geralmente é indicada como recomendada:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. 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.

  1. Abra una nueva terminal integrada (Ctrl + Ñ).
  2. Valide se o prompt de comando mostra o prefixo de ativação na extremidade esquerda:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Instale as bibliotecas necessárias do projeto diretamente dentro do seu ambiente isolado:
Ventana de terminal
pip install google-generativeai requests pandas

3. Resolução de Problemas (Troubleshooting)

Sección titulada «3. Resolución de Problemas (Troubleshooting)»
SintomaCausa RaizSoluçã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.