Como criar um ambiente virtual Python no VS Code e evitar conflitos

Se você instala bibliotecas Python diretamente no sistema, cedo ou tarde um projeto quebra o outro. A solução é criar um ambiente virtual para cada projeto e fazer o VS Code usar esse ambiente, não o Python “global” do computador.

Neste guia, você vai criar uma pasta .venv, ativá-la no terminal, instalar um pacote de teste, selecionar o interpretador correto no VS Code e salvar as dependências para repetir a configuração depois.

O que é um ambiente virtual Python?

Um ambiente virtual é uma instalação isolada de Python dentro da pasta do projeto. Ele tem seu próprio interpretador e sua própria área para pacotes. Assim, uma aplicação pode usar uma versão de uma biblioteca sem alterar as outras aplicações instaladas no computador.

Na prática, a pasta costuma se chamar .venv e fica ao lado dos arquivos do projeto. Ela não deve guardar seu código nem ser enviada ao Git: é um ambiente descartável que pode ser recriado usando uma lista de dependências.

A documentação do Python recomenda o módulo venv para criar esse isolamento. O pip, quando executado com o ambiente ativo, instala os pacotes dentro dele.

Antes de começar

• Tenha o Python instalado. No Linux e no macOS, o comando geralmente é python3; no Windows, use py ou python.
• Instale o Visual Studio Code e a extensão oficial Python, da Microsoft.
• Abra ou crie uma pasta para o projeto. Evite trabalhar em uma pasta sincronizada que possa alterar ou bloquear arquivos automaticamente.

Como criar o ambiente virtual pelo terminal

Abra a pasta do projeto no VS Code e depois abra o terminal integrado em Terminal > New Terminal. Rode o comando correspondente ao seu sistema:

Windows

py -m venv .venv

Linux e macOS

python3 -m venv .venv

O comando cria a pasta .venv e coloca nela um interpretador Python, scripts de ativação e um diretório próprio para os pacotes. Se a pasta já existir, não recrie o ambiente sem necessidade: primeiro tente ativá-lo.

Como ativar o ambiente

Ativar o ambiente faz com que os comandos python e pip apontem para a cópia isolada. O caminho depende do terminal:

Windows PowerShell

.venv\Scripts\Activate.ps1

Windows Prompt de Comando

.venv\Scripts\activate.bat

Linux e macOS

source .venv/bin/activate

Quando funcionar, o nome do ambiente costuma aparecer no começo da linha do terminal, como (.venv). Para confirmar sem depender desse indicador, rode:

python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"

O primeiro resultado deve apontar para a pasta .venv. O segundo deve ser True. No Windows, se o PowerShell bloquear o script de ativação, a própria documentação do Python orienta ajustar a política de execução do usuário ou usar o Prompt de Comando.

Como instalar um pacote sem misturar dependências

Com o ambiente ativo, use o Python dele para chamar o pip. Este exemplo instala a biblioteca Requests:

python -m pip install requests

Prefira python -m pip em vez de apenas pip. Isso reduz a chance de o terminal chamar um pip pertencente a outra instalação do Python.

Teste a instalação com um comando curto:

python -c "import requests; print(requests.__version__)"

Se aparecer uma versão, o pacote está disponível no ambiente que o terminal está usando. Esse teste é mais confiável do que apenas observar uma mensagem de instalação concluída.

Como selecionar o ambiente no VS Code

1. Abra um arquivo com extensão .py.
2. Clique na versão do Python exibida na barra de status, na parte inferior da janela.
3. Escolha o interpretador que termina em .venv/bin/python no Linux e macOS ou .venv\\Scripts\\python.exe no Windows.
4. Se ele não aparecer, abra a Paleta de Comandos com Ctrl+Shift+P ou Cmd+Shift+P e execute Python: Select Interpreter.

O interpretador selecionado será usado para executar e depurar o código. O VS Code também pode descobrir ambientes locais com nomes como .venv e venv; se um ambiente recém-criado não aparecer, use Python Environments: Refresh All Environment Managers ou feche e reabra a pasta.

Uma forma simples de verificar a escolha é criar verificar.py:

import sys

print(sys.executable)
print(sys.version)

Execute o arquivo pelo botão de execução do VS Code. O caminho impresso precisa apontar para o ambiente do projeto. Se o terminal aponta para .venv, mas o botão do editor usa outro Python, o interpretador selecionado na barra de status ainda está errado.

Como salvar e recriar as dependências

Depois de instalar os pacotes necessários, gere um arquivo de requisitos:

python -m pip freeze > requirements.txt

O arquivo registra as versões instaladas naquele ambiente. Envie requirements.txt ao Git, mas inclua .venv/ no .gitignore:

.venv/

Em outro computador, clone o projeto, crie um novo ambiente e instale a lista:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

No Windows, substitua a primeira linha por py -m venv .venv e a ativação por .venv\Scripts\Activate.ps1. O ambiente não deve ser copiado entre computadores: como ele guarda caminhos do interpretador, o procedimento mais seguro é recriá-lo.

Erros comuns e como corrigir

O comando Python não existe

Teste python3 --version no Linux e macOS e py --version no Windows. Se nenhum funcionar, instale o Python pelo site oficial e abra um novo terminal.

O VS Code usa o Python errado

Selecione novamente o interpretador pela barra de status. Depois, abra um novo terminal integrado, pois um terminal que já estava aberto pode continuar com o ambiente anterior.

O PowerShell não permite ativar o ambiente

Você pode usar o Prompt de Comando e executar .venv\Scripts\activate.bat. Se preferir continuar no PowerShell, verifique a política de execução indicada na documentação oficial do Python antes de alterar qualquer configuração.

O pacote foi instalado, mas o editor não encontra o módulo

Compare sys.executable no terminal e no arquivo executado pelo VS Code. Se os caminhos forem diferentes, o pacote foi instalado em um ambiente e o código está rodando em outro.

Preciso ativar o ambiente sempre?

Não obrigatoriamente. O Python permite chamar diretamente o interpretador da pasta, por exemplo .venv/bin/python script.py no Linux e macOS ou .venv\Scripts\python.exe script.py no Windows. Ainda assim, ativar o ambiente costuma ser o caminho mais simples no trabalho diário, porque ajusta o terminal e os comandos instalados.

O ponto importante é não misturar instalações: descubra qual Python executará o projeto e use esse mesmo interpretador para instalar pacotes, rodar testes e iniciar a aplicação. Se você também usa recursos de assistência de código, veja como usar o GitHub Copilot no VS Code para explicar e corrigir código sem perder de vista o ambiente em que o programa realmente roda.

Perguntas frequentes

Para que serve o ambiente virtual Python?

Ele separa o interpretador e os pacotes de um projeto dos demais projetos e da instalação principal do computador, reduzindo conflitos de dependências.

Onde devo criar a pasta .venv?

Na raiz do projeto, normalmente com o nome .venv. A pasta deve ficar fora do controle de versão e pode ser recriada a partir de requirements.txt.

Qual comando instala um pacote no ambiente certo?

Com o ambiente ativo, use python -m pip install nome-do-pacote. Assim, o pip é chamado pelo mesmo interpretador Python que executará o projeto.

O que fazer se o ambiente não aparecer no VS Code?

Abra Python: Select Interpreter na Paleta de Comandos, escolha o executável dentro de .venv e atualize a descoberta de ambientes se necessário.