Ambientes virtuais Python com venv: o que são e como usá-los
O que é um ambiente virtual Python, porque deve usá-lo em todos os projetos e como criá-lo, ativá-lo e geri-lo com o venv no Windows e no Linux.
Assim que se começa a usar o Python a sério, surge um problema: cada projeto precisa das suas bibliotecas, por vezes em versões diferentes. Um script quer uma certa versão de uma biblioteca, outro projeto quer uma mais recente, e instalar tudo no mesmo sítio acaba, mais cedo ou mais tarde, por gerar conflitos difíceis de perceber.
A solução chama-se ambiente virtual. Neste guia vemos o que é, porque vale a pena usá-lo sempre e como geri-lo com o venv, a ferramenta incluída no Python, tanto no Windows como no Linux.
O que é um ambiente virtual
Um ambiente virtual é uma pasta que contém uma cópia isolada do Python com as suas bibliotecas. Quando o ambiente está ativo, tudo o que instala vai para lá, e não para o Python geral do computador.
Pode imaginá-lo como uma caixa de ferramentas dedicada a um único trabalho: cada projeto tem a sua, com as ferramentas de que precisa, e as caixas não se misturam.
As vantagens concretas são três:
- Sem conflitos: dois projetos podem usar versões diferentes da mesma biblioteca.
- O sistema mantém-se limpo: no Linux, em particular, não corre o risco de danificar o Python usado pelo sistema operativo.
- O projeto é reproduzível: pode recriar o mesmo ambiente noutro computador ou num servidor com um único comando.
Antes de começar
Precisa de ter o Python já instalado. No Ubuntu e no Debian, certifique-se também de que tem o módulo venv, que nem sempre está presente:
sudo apt install python3-venv
No Windows, se instalou o Python com o Python Install Manager, o venv já está incluído.
Criar um ambiente virtual
Abra o terminal na pasta do seu projeto e escreva:
# Windows
python -m venv .venv
# Linux e macOS
python3 -m venv .venv
O comando cria uma pasta chamada .venv com tudo o que é necessário. O nome é uma convenção muito difundida: o ponto inicial torna-a «oculta» no Linux e a maioria dos editores reconhece-a automaticamente. Pode dar-lhe o nome que preferir, mas .venv é a escolha mais prática.
No Windows, se tiver várias versões do Python instaladas, pode escolher com qual criar o ambiente:
py -V:3.14 -m venv .venv
O ambiente usará sempre a versão com que foi criado.
Ativar o ambiente
Criar o ambiente não basta: é preciso ativá-lo sempre que abre um novo terminal para trabalhar no projeto. O comando muda consoante o sistema:
# Windows, Linha de Comandos
.venv\Scripts\activate
# Windows, PowerShell
.venv\Scripts\Activate.ps1
# Linux e macOS
source .venv/bin/activate
Quando o ambiente está ativo, o seu nome aparece entre parênteses no início da linha do terminal, por exemplo (.venv). É o sinal de que está a trabalhar dentro do ambiente.
Se o PowerShell bloquear o script de ativação com um erro sobre as políticas de execução, permita a execução de scripts locais para o seu utilizador com este comando, que só precisa de executar uma vez:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
Instalar bibliotecas
Com o ambiente ativo, as bibliotecas instalam-se com o pip, o gestor de pacotes do Python:
python -m pip install requests
Porquê python -m pip e não simplesmente pip? Porque assim tem a certeza de que o pip instala a biblioteca precisamente no Python que está a usar. Com o comando pip sozinho, se o ambiente não estiver ativo ou houver várias versões instaladas, a biblioteca pode ir parar ao sítio errado. É um pequeno hábito que evita muitos problemas.
Para ver as bibliotecas instaladas no ambiente:
python -m pip list
Guardar e recriar as dependências com requirements.txt
As bibliotecas usadas por um projeto chamam-se dependências. Para guardar a sua lista, com as versões exatas, usa-se um ficheiro chamado requirements.txt:
python -m pip freeze > requirements.txt
Noutro computador, ou no servidor, basta criar um novo ambiente virtual, ativá-lo e instalar tudo com um único comando:
python -m pip install -r requirements.txt
O ficheiro requirements.txt deve ser guardado juntamente com o código do projeto. A pasta .venv, pelo contrário, não deve ser copiada nem adicionada ao Git: contém caminhos ligados ao seu computador e recria-se em poucos segundos. Se usa o Git, adicione esta linha ao ficheiro .gitignore:
.venv/
Desativar e eliminar um ambiente
Para sair do ambiente virtual basta escrever:
deactivate
Para o eliminar por completo, apague simplesmente a pasta .venv. Não há nada para desinstalar: tudo o que continha estava lá dentro.
Isto também é útil quando quer mudar a versão do Python de um projeto: apague a pasta, recrie o ambiente com a nova versão e reinstale as dependências a partir do requirements.txt.
Usar o ambiente com o Visual Studio Code
Se usa o Visual Studio Code com a extensão Python, o editor costuma reconhecer sozinho a pasta .venv. Se isso não acontecer, abra a paleta de comandos com Ctrl+Shift+P, procure Python: Select Interpreter e escolha o interpretador que está dentro de .venv. A partir daí, também o terminal integrado ativará o ambiente automaticamente.
Erros comuns e soluções
- «ModuleNotFoundError: No module named …»: quase sempre o ambiente não está ativo, ou a biblioteca foi instalada noutro Python. Ative o ambiente e reinstale a biblioteca com
python -m pip install. - «error: externally-managed-environment» no Linux: está a tentar instalar uma biblioteca no Python do sistema. Crie e ative um ambiente virtual e repita a instalação lá dentro.
- «The virtual environment was not created successfully because ensurepip is not available» no Ubuntu ou no Debian: falta o pacote
python3-venv. Instale-o comsudo apt install python3-venv, apague a pasta.venvincompleta e recrie o ambiente. - O ambiente deixa de funcionar depois de mover ou mudar o nome da pasta do projeto: os ambientes virtuais contêm caminhos absolutos e não suportam ser movidos. Apague-o e recrie-o.
- Erro «Microsoft Visual C++ 14.0 or greater is required» ao instalar uma biblioteca: normalmente o ambiente foi criado com uma versão do Python demasiado recente para essa biblioteca. Dedicámos um artigo a este erro.
Um olhar sobre as ferramentas alternativas
Além do venv existem ferramentas mais completas, como o uv ou o Poetry, que gerem de uma só vez ambientes, dependências e versões do Python. São muito apreciadas nos projetos maiores. Para começar, porém, o venv é a melhor escolha: já vem incluído no Python, funciona em todo o lado e os conceitos que aprendeu aqui também valem para as outras ferramentas.
Resumo
O fluxo de trabalho de qualquer projeto Python resume-se a poucos comandos:
- Uma vez:
python -m venv .venvna pasta do projeto. - Sempre que trabalha no projeto: ative o ambiente.
- Para adicionar bibliotecas:
python -m pip install nomee depois atualize orequirements.txt. - Noutro computador: crie o ambiente, ative-o e execute
python -m pip install -r requirements.txt.
Fontes oficiais
Partilhar
Qual é a sua reação?
Gosto
0
Não gosto
0
Adoro
0
Divertido
0
Irritado
0
Triste
0
Uau
0