Você instala uma biblioteca para um projeto e, de repente, outro deixa de funcionar. Ou o tutorial pede uma versão de um pacote e você tem outra. Esse tipo de conflito é tão comum em Python que existe uma solução padrão: o ambiente virtual.
Se você está no começo, passe antes por Python para iniciantes: seus primeiros passos.
O que é um ambiente virtual
É uma pasta que contém uma cópia (ou um atalho) do interpretador Python e um espaço próprio para pacotes. Quando o ambiente está ativo, tudo o que você instala com o pip vai para essa pasta, e não para o Python geral do computador.
Benefícios:
- Isolamento: cada projeto tem as versões de que precisa.
- Organização: você sabe exatamente quais pacotes o projeto usa.
- Reprodução: outra pessoa (ou você, em outro computador) recria o mesmo ambiente com uma lista.
- Segurança: erros de instalação ficam contidos e podem ser descartados apagando a pasta.
O que é o pip
O pip é o instalador de pacotes do Python. Com ele você baixa bibliotecas do repositório oficial (PyPI). Comandos mais usados:
- pip install nome-do-pacote: instala;
- pip uninstall nome-do-pacote: remove;
- pip list: lista o que está instalado;
- pip install --upgrade nome-do-pacote: atualiza.
Passo a passo para criar e usar um ambiente
- Abra o terminal na pasta do projeto. Em caso de dúvida sobre navegação, veja comandos básicos do terminal.
- Crie o ambiente com o comando python -m venv .venv. Em Mac e Linux, pode ser necessário usar python3 no lugar de python. O nome .venv é uma convenção; você pode escolher outro.
- Ative o ambiente:
- no Windows (Prompt de Comando): .venv\Scripts\activate;
- no Windows (PowerShell): .venv\Scripts\Activate.ps1;
- no Mac e no Linux: source .venv/bin/activate.
- Confira se ativou. O nome do ambiente aparece entre parênteses no início da linha do terminal.
- Instale os pacotes que precisar, com pip install.
- Rode seus scripts normalmente. Eles usarão os pacotes do ambiente.
- Para sair, digite deactivate.
Salvar e recriar a lista de pacotes
Para que o projeto seja reproduzível, grave os pacotes e versões num arquivo:
- pip freeze > requirements.txt cria o arquivo com tudo o que está instalado no ambiente ativo.
Em outro computador, ou depois de apagar o ambiente:
- crie e ative um novo ambiente;
- rode pip install -r requirements.txt.
Pronto: os mesmos pacotes estão disponíveis. O arquivo requirements.txt deve ir para o Git junto com o código (veja Git no dia a dia), enquanto a pasta .venv fica no .gitignore.
Erros comuns e soluções
- “python não é reconhecido como comando” (Windows): o Python não foi adicionado ao PATH na instalação. Reinstale marcando a opção correspondente, ou use o comando py, que costuma estar disponível.
- “pip não é reconhecido”: tente python -m pip install nome, que usa o pip do Python que você está chamando.
- Pacote instalado mas “ModuleNotFoundError”: você instalou em um ambiente e roda o script em outro. Confira se o ambiente está ativo e qual Python o editor usa.
- Erro de permissão ao instalar: provavelmente está fora do ambiente virtual, instalando no Python do sistema. Ative o ambiente e tente de novo, sem usar permissões de administrador.
- Versões incompatíveis: o pip mostra a mensagem de conflito. Leia o aviso completo, que costuma indicar o pacote e a versão problemática. Veja como ler mensagens de erro.
- Ambiente quebrado: apague a pasta .venv, crie outra e reinstale com o requirements.txt. É rápido e resolve muita coisa.
O editor precisa saber qual ambiente usar
Editores como o VS Code detectam o ambiente na pasta do projeto, mas às vezes é preciso escolher o interpretador manualmente. Procure a opção de selecionar interpretador Python no editor (o nome pode variar conforme a versão). Detalhes em configurar o VS Code para programar.
Outras ferramentas
Existem alternativas, como o conda (comum em ciência de dados) e gerenciadores mais novos que combinam ambiente e dependências. Para quem está começando, o venv com pip basta e vem no próprio Python. Aprenda esse fluxo antes de migrar para outro.
Quando usar mais de uma versão do Python
Às vezes um projeto exige uma versão específica do Python, diferente da que está instalada. O ambiente virtual usa a versão com a qual foi criado. Portanto, se você precisa de outra, instale-a primeiro e crie o ambiente chamando justamente essa versão. No Windows, o comando py aceita escolher a versão desejada; em Mac e Linux, costuma-se chamar python3 com o número da versão, como python3.12.
Depois de criado, anote a versão usada no README do projeto. Assim, quem for rodar o código depois, inclusive você mesmo, sabe qual Python usar e evita erros estranhos de compatibilidade.
Cuidados de segurança
Instale apenas pacotes de que você conhece a origem. Nomes parecidos com bibliotecas famosas podem ser armadilhas, e é um risco real quando uma IA sugere um pacote. Confira o nome na página oficial do PyPI antes de instalar, e leia mais em segurança básica em código.
Crie o hábito: um projeto novo, um ambiente novo. Com os comandos acima, leva menos de um minuto e evita horas de conflitos.