Projeto Python de IA no Windows: crie um venv e confira onde o pip instala

Um projeto de IA em Python pode pedir a instalação de bibliotecas antes mesmo do primeiro teste. O problema é descobrir qual Python receberá esses pacotes. Quando há mais de uma instalação no computador, um pip install solto pode atingir um ambiente diferente daquele que executará o projeto. Neste guia, você cria um ambiente virtual no Windows e confere o caminho do interpretador antes de instalar qualquer dependência externa.

Os comandos abaixo seguem a documentação oficial do Python e da PyPA, consultada em 19 de outubro de 2026. Eles não foram executados em uma instalação Windows durante a preparação deste artigo. O teste inicial usa apenas a biblioteca padrão e o pip incluído no ambiente, sem baixar um pacote de terceiros. A capa é uma ilustração conceitual original, não uma captura real do terminal.

O que você vai obter e o que o venv não faz

Ao final, seu projeto terá uma pasta .venv com um interpretador Python próprio. Um comando mostrará o caminho desse interpretador e outro confirmará que ele está em um ambiente virtual. A documentação do módulo venv explica que as bibliotecas instaladas ali ficam, por padrão, separadas das bibliotecas do Python de base. Isso reduz conflitos de versões entre projetos.

Essa separação não é uma barreira de segurança. Código ou pacote executado dentro do venv ainda pode acessar arquivos e rede de acordo com as permissões da sua conta. Se o projeto veio de uma resposta de IA ou de origem desconhecida, faça antes a triagem dos manifestos e scripts de instalação. Para um primeiro teste de código não confiável, use um ambiente realmente isolado, como o descrito no guia de Windows Sandbox, quando essa opção estiver disponível.

Pré-requisitos e pasta de trabalho

Você precisa de uma instalação confiável de Python 3 para Windows, PowerShell e uma pasta de projeto sob seu controle. A PyPA recomenda usar ambientes virtuais ao trabalhar com pacotes de terceiros e parte de uma instalação oficial do Python. Se ainda não tem Python, obtenha-o pela página oficial de downloads, não por um instalador sugerido em uma conversa sem conferir a origem.

Abra o PowerShell dentro da pasta do seu projeto. A pasta deve ser sua, não uma instalação do sistema nem um projeto de outra pessoa que você não revisou. Antes de criar arquivos, confira onde está:

Get-Location
python --version
Get-Command python | Select-Object -ExpandProperty Source

O resultado esperado é uma versão de Python 3 e um caminho para o comando python que você reconhece. O número da versão depende da sua instalação. Se o comando não for encontrado ou apontar para um alias sem Python instalado, resolva isso antes de continuar. O comando py -m venv .venv usado pela PyPA no Windows é uma alternativa quando o gerenciador py está disponível; use o executável que você efetivamente verificou.

Passo 1: crie o ambiente sem sobrescrever outro

Procure primeiro uma pasta .venv existente. Se ela já estiver lá, não rode um comando de limpeza para “começar do zero”. Verifique se pertence a este projeto e se alguém depende dela:

if (Test-Path -LiteralPath '.\.venv') {
    throw 'A pasta .venv já existe; verifique antes de continuar.'
}
python -m venv .venv

Execute o bloco somente se o Python exibido no passo anterior for o escolhido para o projeto. A trava interrompe a execução quando já existe uma pasta .venv; ela não apaga nem altera esse ambiente. O venv cria o arquivo pyvenv.cfg, a pasta Scripts e os diretórios de bibliotecas. Por padrão ele prepara o pip, salvo se você solicitar explicitamente --without-pip. Não use --clear: essa opção remove o conteúdo de uma pasta de ambiente já existente.

O resultado esperado é a presença de .\.venv\Scripts\python.exe. Se a criação falhar por permissão, escolha uma pasta de projeto gravável em vez de executar o PowerShell como administrador. Se falhar porque o Python não foi encontrado, volte à verificação de instalação e do comando, sem baixar scripts de correção de origem incerta.

Passo 2: confirme o Python que vai executar o projeto

A ativação do venv é opcional. O próprio Python documenta que você pode chamar diretamente o interpretador dentro dele. Isso evita mudar a política de execução do PowerShell apenas para rodar o script Activate.ps1. Na mesma pasta do projeto, use:

& .\.venv\Scripts\python.exe -c 'import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)'

A primeira linha da saída deve terminar em .venv\Scripts\python.exe, embora a parte anterior varie. A segunda deve ser True. Pela referência oficial, comparar sys.prefix com sys.base_prefix é uma forma de confirmar que o interpretador roda dentro de um ambiente virtual. Se aparecer False, pare: você não está executando o Python do venv esperado.

Um prompt com (.venv) não é a única prova possível, nem é necessário para este fluxo. Ao abrir outra janela de PowerShell, repita o comando com o caminho explícito. Isso diminui o risco de usar por engano o Python global em uma sessão nova.

Passo 3: confira o pip antes de instalar

Agora invoque o pip como módulo do mesmo interpretador. A forma python -m pip mantém visível qual Python está executando o gerenciador:

& .\.venv\Scripts\python.exe -m pip --version
& .\.venv\Scripts\python.exe -m pip check

No primeiro resultado, confirme que o caminho do pip contém a .venv do projeto. O segundo comando usa o pip check para procurar incompatibilidades entre dependências já instaladas. Em um ambiente recém-criado, é normal não haver pacotes do projeto a verificar. Uma resposta sem erros não certifica a segurança de um pacote nem garante que o seu aplicativo funcionará.

Se o pip não estiver presente, confira se o venv foi criado com --without-pip e consulte a documentação da instalação de Python antes de tentar comandos de bootstrap. Não use sudo, não altere a instalação global e não troque de índice de pacotes por uma sugestão sem verificar a procedência.

Passo 4: instale apenas dependências que você revisou

Somente depois de verificar origem, nomes, versões, arquivos de controle e scripts, instale o que o projeto realmente exige. Se houver um requirements.txt confiável e aprovado, o comando tem esta forma:

& .\.venv\Scripts\python.exe -m pip install -r .\requirements.txt
& .\.venv\Scripts\python.exe -m pip check

Essa etapa acessa a fonte de pacotes configurada e executa o processo de instalação, por isso não faz parte do teste sem download deste guia. A PyPA documenta o uso de arquivos de requisitos, mas o arquivo continua sendo entrada a revisar, não uma autorização automática. Se não existe lista aprovada, pare aqui. Inventar um nome de pacote para “testar” só acrescentaria risco e pouco aprendizado.

Depois de instalar, rode o aplicativo com .\.venv\Scripts\python.exe e o comando próprio do projeto, que deve ter sido inspecionado. Não execute um script apenas porque uma IA sugeriu que é o próximo passo. O venv ajuda a organizar dependências; ele não interpreta a intenção de um script nem bloqueia leitura de credenciais.

Como registrar o ambiente sem copiar a pasta .venv

A pasta .venv é local e descartável. A documentação do Python orienta recriá-la no destino em vez de movê-la ou copiá-la, porque caminhos internos podem ser absolutos. Também recomenda não colocá-la no controle de versão. Revise seu .gitignore e confirme que a pasta não entrará em um commit ou pacote de entrega.

Para registrar o que está instalado no momento, você pode usar:

& .\.venv\Scripts\python.exe -m pip freeze

O pip freeze lista pacotes instalados em formato de requisitos. Isso é um retrato do ambiente, não um arquivo de trava calculado pelo resolvedor nem uma auditoria de licenças ou vulnerabilidades. Revise a lista antes de compartilhá-la e mantenha o arquivo de requisitos do projeto sob controle editorial próprio.

Erros comuns e critérios para parar

• python não é encontrado: confira instalação e caminho oficial. Não avance com outro executável que você não reconhece.
• A pasta .venv já existe: descubra a quem pertence. Não use --clear e não apague a pasta sem autorização e cópia adequada.
• Activate.ps1 é bloqueado: chame diretamente .\.venv\Scripts\python.exe. A ativação não é necessária e não exige afrouxar a política da máquina.
• O teste de sys.prefix retorna False: verifique pasta e caminho do executável; não instale pacotes até corrigir.
• pip check acusa conflito: registre o pacote e a exigência exibidos; revise a lista de dependências e a compatibilidade, sem forçar uma instalação global.
• O projeto veio de origem incerta: interrompa antes de pip install ou de executar código. O venv não protege seus arquivos e segredos.

O critério de conclusão é simples: você reconhece a instalação base, criou um venv novo para este projeto, obteve True na comparação de prefixos e viu o pip apontar para a mesma pasta. Só então passe à instalação de dependências previamente verificadas.