O problema
Instalar pacotes globalmente no Python do sistema é o caminho mais rápido para conflitos, upgrades quebrados e “funciona na minha máquina”. O venv resolve isso com três linhas.
Dois projetos pedem versões diferentes da mesma biblioteca. Sem isolamento, um sobrescreve o outro. Em servidores, o Python do SO é usado por ferramentas do próprio sistema — poluí-lo é risco operacional.
A solução em 30 segundos
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
pip install -r requirements.txtNo Windows PowerShell: .venv\Scripts\Activate.ps1.
Boas práticas
- Sempre pin versions no
requirements.txt(pip freeze) - Coloque
.venv/no.gitignore - Em Docker, o próprio container já isola — ainda assim use venv se preferir
- Documente no README o comando de ativação
Quer ir além?
Isso é só o começo do nosso curso Automações em Python — módulo 1 cobre setup completo e o primeiro script de produção.
Comandos explicados
| Comando | O que faz |
|---|---|
python3 -m venv .venv | Cria o ambiente isolado na pasta .venv. O -m venv executa o módulo venv do Python. |
source .venv/bin/activate | Ativa o ambiente no Linux e no macOS. A partir daí, python e pip apontam para o .venv. |
.venv\Scripts\Activate.ps1 | Faz o mesmo no PowerShell do Windows. |
pip install -r requirements.txt | Instala os pacotes listados no arquivo de dependências. |
pip freeze > requirements.txt | Grava as versões instaladas no requirements.txt, para reproduzir o ambiente depois. |
deactivate | Sai do ambiente virtual. |
Exemplo: como saber se o venv está ativo
$ which python
/usr/bin/python
$ source .venv/bin/activate
(.venv) $ which python
/home/usuario/projeto/.venv/bin/pythonO (.venv) no início do prompt e o caminho de which python apontando para dentro do projeto mostram que o ambiente está ativo. Se o prompt não mostra o nome, os pacotes estão indo para o Python do sistema.
Erros comuns e como resolver
| Mensagem | Causa provável | Solução |
|---|---|---|
ensurepip is not available | No Debian e no Ubuntu, o suporte a venv vem em um pacote separado. | Instale com sudo apt install python3-venv. |
externally-managed-environment | O sistema protege o Python global, e o pip install foi feito fora de um venv. | Crie e ative um venv, e instale os pacotes nele. |
| O PowerShell diz que a execução de scripts está desabilitada | A política de execução do Windows bloqueia o Activate.ps1. | Libere para o seu usuário com Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. |
| Um pacote instalado "não aparece" no projeto | A instalação foi feita fora do venv. | Ative o ambiente e confira com pip list. |