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.

Ambientes virtuais Python com venv: o que são e como usá-los

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 com sudo apt install python3-venv, apague a pasta .venv incompleta 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 .venv na pasta do projeto.
  • Sempre que trabalha no projeto: ative o ambiente.
  • Para adicionar bibliotecas: python -m pip install nome e depois atualize o requirements.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 Gosto 0
Não gosto Não gosto 0
Adoro Adoro 0
Divertido Divertido 0
Irritado Irritado 0
Triste Triste 0
Uau Uau 0