Como criar um ambiente virtual Python no Windows e usar no VS Code

Para criar um ambiente virtual Python no Windows, abra a pasta do projeto no terminal e rode py -m venv .venv. Depois, ative o ambiente com .\.venv\Scripts\Activate.ps1 no PowerShell ou .venv\Scripts\activate.bat no Prompt de Comando. A partir daí, os pacotes instalados ficam separados do Python global.

Essa configuração evita um problema comum: um projeto precisa de uma versão de uma biblioteca, enquanto outro depende de uma versão diferente. O venv cria uma pequena “caixa” para cada projeto — não é uma máquina virtual e não protege o computador contra código malicioso. Neste guia, você vai criar o ambiente, escolher o interpretador no VS Code, instalar um pacote e testar se tudo está funcionando.

O que você precisa antes de começar

• Windows 10 ou 11;
• Python instalado pelo site oficial do Python;
• Visual Studio Code instalado;
• extensão Python da Microsoft adicionada ao VS Code;
• uma pasta vazia para o projeto.

O VS Code é o editor; ele não instala o Python sozinho. O interpretador é o programa que realmente executa os arquivos .py. Depois da instalação, abra o PowerShell e teste com py --version. Se esse comando não funcionar, tente python --version. O resultado deve mostrar uma versão do Python, em vez de uma mensagem de comando não encontrado.

O que é um ambiente virtual Python?

Um ambiente virtual é uma instalação independente, criada em uma pasta do projeto, que mantém seu próprio conjunto de bibliotecas. O módulo oficial venv cria essa estrutura a partir do Python que já está instalado no computador. No Windows, os executáveis e scripts ficam dentro de .venv\Scripts.

Imagine dois projetos: um precisa do pacote requests atualizado e outro depende de uma versão antiga. Sem isolamento, uma instalação pode afetar a outra. Com um ambiente por projeto, cada pasta tem seus próprios pacotes. A prática recomendada é deixar o ambiente descartável e guardar a lista de dependências em um arquivo, não no repositório.

Como criar o ambiente virtual no Windows

1. Crie ou abra a pasta do projeto

No Explorador de Arquivos, crie uma pasta chamada meu-projeto. Clique na barra de endereço, digite powershell e pressione Enter. Outra opção é abrir o terminal do VS Code depois de carregar essa pasta.

cd caminho\para\meu-projeto

Se a pasta estiver, por exemplo, em Documentos, o comando pode ser parecido com cd "$HOME\Documents\meu-projeto" no PowerShell. O importante é que o terminal esteja na raiz do projeto antes de criar o ambiente.

2. Rode o comando do venv

py -m venv .venv

O comando pede ao Python para executar o módulo venv e criar uma pasta chamada .venv. O ponto no começo deixa a pasta menos chamativa e também é um nome que o VS Code costuma detectar automaticamente. Se ela já existir, não crie outro ambiente por cima sem saber o que está fazendo; apague e recrie apenas se não houver dependências importantes ali.

3. Ative o ambiente no PowerShell

.\.venv\Scripts\Activate.ps1

Quando der certo, o terminal normalmente passa a mostrar (.venv) no começo da linha. Isso indica que comandos como python e pip serão direcionados para o ambiente do projeto. Para quem usa o Prompt de Comando, o equivalente é:

.venv\Scripts\activate.bat

4. Confirme qual Python está ativo

python --version
python -m pip --version

O segundo resultado deve apontar para um caminho dentro da pasta .venv. Usar python -m pip é mais seguro do que chamar apenas pip, porque deixa claro qual interpretador está recebendo a instalação.

Como resolver o erro do Activate.ps1

Se o PowerShell disser que não pode executar Activate.ps1, o bloqueio vem da política de execução de scripts. A documentação do Python sugere habilitar scripts assinados localmente para o usuário atual:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Confirme a alteração apenas se entender a política do computador. Em máquinas de empresa ou escola, uma regra de grupo pode impedir a mudança; nesse caso, fale com o administrador ou use o Prompt de Comando. Não é necessário desativar a segurança do Windows inteira para ativar um ambiente.

Como selecionar o ambiente no VS Code

1. Abra a pasta do projeto no VS Code;
2. pressione Ctrl+Shift+P;
3. execute Python: Select Interpreter;
4. escolha o Python que termina em .venv\Scripts\python.exe;
5. abra um novo terminal integrado e confirme se (.venv) aparece.

O interpretador selecionado é usado para executar o código, depurar e oferecer recursos como IntelliSense. Se o VS Code não mostrar o ambiente, feche e abra a pasta novamente, use o comando Python: Select Interpreter para atualizar a lista e confira se a extensão Python está instalada.

A documentação do VS Code também informa que ambientes locais chamados .venv e venv são descobertos automaticamente em muitos projetos. Ainda assim, não confie apenas no nome: verifique o caminho exibido na barra de status e teste o arquivo.

Como instalar uma biblioteca e testar

Com o ambiente ativo, instale uma biblioteca simples:

python -m pip install requests

Agora crie um arquivo chamado teste.py com este conteúdo:

import requests

resposta = requests.get("https://example.com", timeout=10)
print(resposta.status_code)

Execute no terminal:

python teste.py

Se aparecer um código como 200, o Python conseguiu executar o arquivo e usar a biblioteca instalada. O teste não prova que seu projeto inteiro está correto, mas confirma as três peças principais: interpretador, ambiente e pacote.

Como salvar as dependências do projeto

Depois de instalar os pacotes, gere um arquivo com as versões usadas:

python -m pip freeze > requirements.txt

Em outro computador, crie um novo .venv, ative-o e rode:

python -m pip install -r requirements.txt

Não envie a pasta .venv para o Git. Adicione estas linhas ao arquivo .gitignore:

.venv/
__pycache__/
*.pyc

A pasta do ambiente pode ficar grande e contém arquivos específicos do computador. O que precisa ser compartilhado é o código e a descrição das dependências. Se você estiver avançando para integrações web, o nosso guia sobre como criar uma API com Google Apps Script e Google Sheets mostra outro caminho prático para expor dados sem montar toda a infraestrutura do zero.

Como desativar ou recriar o ambiente

Quando terminar o trabalho, saia do ambiente com:

deactivate

Para ativá-lo novamente, execute o comando correspondente ao seu terminal. Se algo quebrar e você tiver um requirements.txt, pode fechar o terminal, apagar a pasta .venv, criar outra com py -m venv .venv e reinstalar as dependências. Essa possibilidade de recriação é uma das vantagens do venv.

Problemas comuns e como identificar a causa

• “py não é reconhecido”: o Python Launcher não está instalado ou não está no PATH. Refaça a instalação pelo Python.org e confira as opções oferecidas pelo instalador.
• O pacote foi instalado, mas o VS Code sublinha o import: o editor provavelmente está usando outro interpretador. Selecione o arquivo dentro de .venv\Scripts.
• O comando funciona em um terminal, mas não em outro: cada terminal tem sua própria sessão. Ative o ambiente novamente ou use o caminho completo do Python.
• O projeto parou depois de trocar de computador: não copie o .venv. Recrie-o e instale as dependências a partir do arquivo de requisitos.
• O script de ativação foi bloqueado: use o Prompt de Comando ou revise a política do PowerShell no escopo correto; não baixe um script aleatório da internet.

Perguntas frequentes

O ambiente virtual Python é uma máquina virtual?

Não. O venv é uma pasta isolada com um interpretador e os pacotes do projeto. Ele não simula um computador inteiro nem oferece o mesmo isolamento de uma máquina virtual.

Preciso ativar o venv toda vez que abrir o projeto?

Você precisa ativá-lo no terminal em que vai executar os comandos, mas não precisa ativá-lo para sempre. Também é possível chamar diretamente o Python dentro da pasta .venv.

Posso apagar a pasta .venv?

Sim. Ela é recriável e não deve guardar o código do projeto. Antes, mantenha um requirements.txt ou pyproject.toml para instalar novamente as dependências.