Ambiente virtual no Python: venv, pip e o erro "externally-managed-environment"

Como criar e usar um ambiente virtual Python no Linux, macOS e Windows, guardar as dependências do projeto, e por que o pip install fora do venv agora dá erro nas distribuições Linux recentes.

Fala pessoal.

Gerenciar dependências em projetos Python pode virar dor de cabeça, principalmente quando você trabalha em vários projetos que precisam de versões diferentes do mesmo pacote. A solução é o ambiente virtual: uma pasta isolada, com o seu próprio Python e os seus próprios pacotes, separada do sistema e dos outros projetos.

Por que isso ficou ainda mais importante

Se você usa uma distribuição Linux recente (Debian 12, Ubuntu 23.04 em diante, Fedora...) e tentou um pip install direto no sistema, provavelmente viu isto:

$ pip install requests
error: externally-managed-environment

× This environment is externally managed

Não é bug. As distribuições passaram a proteger o Python do sistema, porque ferramentas do próprio sistema operacional dependem dele, e um pip install global podia quebrá-las. O recado é claro: instale pacotes dentro de um ambiente virtual.

Criando o ambiente

No Debian e no Ubuntu, o módulo venv vem em um pacote separado:

sudo apt install python3-venv

Dentro da pasta do projeto, crie o ambiente. O nome .venv é o mais comum, e editores como o VS Code já o reconhecem sozinhos:

cd meu-projeto
python3 -m venv .venv

Ativando

# Linux e macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

Com o ambiente ativo, o nome dele aparece no início do prompt, como (.venv). A partir daí, python e pip são os do ambiente.

⚠️ No Windows, se o PowerShell recusar o script de ativação, libere a execução de scripts locais para o seu usuário: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Instalando e registrando as dependências

# instala o que o projeto precisa
pip install flask requests

# registra as versões instaladas
pip freeze > requirements.txt

# em outra máquina (ou num servidor), recria tudo igual
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# para sair do ambiente
deactivate

💡 Dica: nunca coloque a pasta .venv no Git. Ela é grande e depende da máquina. O que vai para o repositório é o requirements.txt. Adicione .venv/ ao seu .gitignore.

E as ferramentas de linha de comando?

Para programas que você só quer usar (e não importar no seu código), como ansible, httpie ou yt-dlp, existe o pipx. Ele cria um ambiente virtual para cada ferramenta automaticamente:

sudo apt install pipx
pipx install httpie

Uma alternativa mais rápida: uv

Nos últimos tempos, o uv ganhou muito espaço. Ele faz o papel do venv e do pip, só que bem mais rápido, com comandos quase iguais:

uv venv
uv pip install -r requirements.txt

Vale testar, mas o venv + pip continua sendo o padrão que funciona em qualquer lugar, sem instalar nada além do Python.

Considerações Finais

Ambiente virtual deixou de ser boa prática opcional e virou o caminho normal, até porque as distribuições Linux já não deixam fazer diferente. Um .venv por projeto e um requirements.txt no Git evitam o famoso "na minha máquina funciona".

No próximo passo, dá para usar esse ambiente para subir um servidor web local com Python e Flask.

Abs e até a próxima!!!

:wq!

Post publicado originalmente em agosto de 2024 e atualizado em novembro de 2026.