Python: como criar e usar um ambiente virtual para cada projeto

Um ambiente virtual é um diretório associado a uma instalação de Python que mantém o seu próprio conjunto de pacotes. O módulo padrão venv permite criá-lo e, por predefinição, isola os seus pacotes dos instalados na instalação base. Assim, cada projeto pode ter dependências independentes, em vez de partilhar necessariamente uma única coleção de pacotes em todo o computador. Documentação oficial de venv

Imagine dois projetos: um requer uma versão específica de uma biblioteca e o outro depende de uma versão diferente. Instalar ambas no mesmo ambiente global pode causar incompatibilidades. Com um ambiente separado para cada projeto, cada um pode instalar os seus pacotes sem alterar o conjunto do outro. A principal vantagem é o isolamento das dependências, não uma separação completa do sistema nem a garantia de que o projeto será executado da mesma forma em qualquer computador.

venv está incluído na biblioteca padrão do Python desde a versão 3.3. O ambiente é criado sobre uma instalação de Python existente, conhecida como Python base, e utiliza a versão do interpretador com que foi criado. Por isso, criar um ambiente não instala por si só qualquer versão de Python de que o projeto possa precisar: é necessário dispor primeiro do interpretador adequado. Documentação oficial de venv

Antes de criar o ambiente, abra um terminal e confirme que o Python está disponível. Os nomes dos comandos podem variar consoante o sistema e o método de instalação. No macOS e em muitas distribuições Linux, é habitual experimentar python3 --version; no Windows, py --version ou python --version. Se um comando não for reconhecido, experimente as outras opções disponíveis e verifique que interpretador cada uma invoca. Este guia não pressupõe que todos os computadores tenham o mesmo comando.

Crie ou abra a pasta do projeto e execute os comandos a partir daí. .venv é um nome habitual para o diretório do ambiente: o ponto inicial faz com que alguns exploradores de ficheiros o apresentem como oculto, mas não altera o funcionamento do Python. O Python Packaging User Guide também recomenda trabalhar num ambiente virtual ao instalar pacotes para um projeto. Python Packaging User Guide

Confirme também que tem permissão para escrever na pasta e que o interpretador selecionado é aquele que pretende utilizar. Se tiver várias instalações, o resultado de --version ajuda a detetar uma seleção inesperada. O ambiente herda a versão do Python usada para o criar, por isso convém decidir qual utilizar antes de instalar pacotes.

A localização a partir da qual executa o comando é importante, porque .venv será criada na pasta atual. Mantê-la dentro do projeto facilita perceber a que projeto pertence o ambiente. Se já existir um diretório .venv, verifique o seu conteúdo e finalidade antes de tentar criar outro no mesmo caminho. Escolha o interpretador com cuidado: num computador com várias versões do Python, o nome do comando, por si só, não indica qual instalação será utilizada.

O módulo é executado como módulo Python: -m venv indica ao interpretador que invoque venv, e .venv é o diretório a criar. Utilize o comando adequado à sua instalação:

• Windows: py -m venv .venv (se o launcher py não estiver disponível, experimente python -m venv .venv).
• macOS ou Linux: python3 -m venv .venv (se python3 não existir, confirme se python aponta para o interpretador pretendido).

A documentação explica que a criação gera o diretório de destino e ficheiros de configuração. Dentro do ambiente, os executáveis estão organizados de forma diferente consoante a plataforma: no Windows, encontram-se em Scripts; em sistemas do tipo Unix, como macOS e Linux, em bin. Documentação oficial de venv Normalmente, a criação não apresenta uma confirmação detalhada; pode verificar o resultado procurando .venv na pasta do projeto. Se o comando falhar, leia a mensagem completa antes de voltar a tentar: pode indicar um interpretador inexistente, uma pasta sem permissões de escrita ou um ambiente incompleto. Não presuma que repetir o mesmo comando resolverá a causa. Se o destino já existir, examine-o antes de decidir o que fazer, em vez de eliminar ficheiros sem verificar a sua finalidade. A estrutura do comando mantém-se semelhante entre plataformas, mas o comando do interpretador e a organização dos diretórios resultantes podem variar. Manter o diretório do ambiente dentro do projeto também facilita seguir os comandos de ativação posteriores. Depois de criado, o ambiente pode ser ativado com o script adequado à shell que está a utilizar. A criação não instala, por si só, os pacotes do projeto: essa instalação é uma etapa separada, realizada depois da ativação. É útil distinguir claramente a criação do ambiente, a instalação dos pacotes e a execução do projeto. Se não souber que interpretador foi invocado, volte à verificação da versão do Python e confirme a instalação antes de continuar. Assim, evita criar o ambiente do projeto com uma versão inesperada. Não é necessária uma mensagem específica de confirmação para que a criação tenha sido bem-sucedida: a presença do diretório e dos ficheiros do ambiente é a verificação prática descrita aqui. Em contrapartida, uma mensagem de erro deve ser compreendida antes de prosseguir. Ao verificar a pasta e ler a mensagem, poderá distinguir um problema de criação de um problema posterior de ativação ou instalação de pacotes. O nome .venv é convencional, não obrigatório: nestes exemplos, é o nome escolhido para o destino, pelo que deve utilizar o mesmo nome nos comandos seguintes. Se escolher outro nome, os caminhos de ativação terão de corresponder. Os exemplos abaixo pressupõem que manteve .venv. Dessa forma, os comandos são consistentes desde a criação até à ativação e posterior desativação. O ambiente continua associado à instalação do Python usada para o criar, razão pela qual é importante selecionar o interpretador antecipadamente. O comando cria um ambiente local na pasta atual do projeto; não copia todo o sistema operativo nem substitui a instalação base do Python. Estes limites ajudam a compreender o que significa “isolado” neste contexto. O passo seguinte é ativar o ambiente no terminal em que pretende trabalhar. Se abrir outro terminal mais tarde, poderá ser necessário ativá-lo novamente nessa sessão. É um comportamento esperado, não um sinal de que o ambiente foi eliminado. Os ficheiros permanecem em .venv até serem removidos.**

Assim, venv fornece uma área de trabalho local para os pacotes de cada projeto, criada com o interpretador Python selecionado. O diretório de executáveis específico de cada plataforma explica por que razão os caminhos de ativação diferem, apesar de o método de criação ser semelhante. Depois de confirmar que o diretório existe, avance para o comando de ativação adequado ao seu terminal.

Depois de criado, ative o ambiente com o script adequado à shell que está a utilizar. No macOS e Linux, a partir da pasta do projeto, execute source .venv/bin/activate. No Windows, o comando varia consoante o terminal: no PowerShell, utilize .venv\Scripts\Activate.ps1; na Linha de Comandos, .venv\Scripts\activate.bat. Ao copiar qualquer um dos comandos, não inclua um espaço inicial.

Depois de ativado, o terminal costuma apresentar (.venv) no início do indicador. É um sinal prático, mas não a única verificação possível. Pode então instalar uma biblioteca, por exemplo com python -m pip install nome-do-pacote. Invocar pip através do python ativo ajuda a associar a instalação ao interpretador selecionado. A documentação de packaging descreve o fluxo de instalação com pip dentro de um ambiente virtual. Python Packaging User Guide

Execute o programa com python ficheiro.py, substituindo ficheiro.py pelo nome real do ficheiro. Para confirmar que interpretador está a utilizar, python --version apresenta a versão; também pode consultar o caminho com python -c "import sys; print(sys.executable)". Instale e execute com o mesmo ambiente ativo: assim reduz o risco de instalar um pacote numa instalação e executar o projeto com outra.

O comando de ativação específico da shell altera a sessão atual do terminal para que comandos como python utilizem o interpretador do ambiente. Por isso, é importante ativar o ambiente no terminal em que pretende instalar pacotes e executar o projeto. Se abrir outro terminal, não presuma que já está a utilizar o mesmo ambiente: ative-o também nessa janela e confirme o indicador ou o caminho do interpretador. Esta verificação simples pode ajudar a perceber por que motivo um pacote parece não estar disponível, apesar de o comando de instalação aparentemente ter sido bem-sucedido. Utilize o nome real do ficheiro ao executar o programa e permaneça na pasta do projeto, salvo se este exigir outro diretório de trabalho. Os exemplos são comandos para introduzir no terminal, não texto a acrescentar ao ficheiro Python.

Para sair do ambiente ativo, escreva deactivate e prima Enter. O comando deixa de utilizar o ambiente virtual nesse terminal; não elimina os ficheiros de .venv nem desinstala os seus pacotes. Para voltar a trabalhar no projeto, abra um terminal na respetiva pasta e repita o comando de ativação adequado ao Windows, macOS ou Linux. Documentação oficial de venv

Se a ativação falhar no PowerShell com uma mensagem sobre a execução de scripts, não altere às cegas as definições de segurança do computador. Pode utilizar outro terminal compatível, como a Linha de Comandos, e consultar a documentação de Python para Windows para resolver a configuração específica da instalação. Microsoft Learn: Python no Windows Se surgir “comando não encontrado”, confirme primeiro que está na pasta do projeto, que .venv existe e que escreveu o caminho correspondente à sua plataforma.

Se pip indicar que um pacote já está instalado, mas o programa não o encontrar, verifique sys.executable e o caminho de instalação: o terminal pode não estar a utilizar o ambiente esperado. Se a criação falhar porque venv não está disponível, verifique a instalação e os componentes de Python do sistema; os detalhes dependem da forma como o Python foi instalado. Não elimine uma instalação global como primeira medida.

Ao diagnosticar um problema, examine as etapas separadamente em vez de alterar várias definições ao mesmo tempo. Primeiro confirme a pasta e o diretório do ambiente, depois verifique o caminho do interpretador e, por fim, repita o comando relevante. A ausência de (.venv) no indicador pode ser uma pista, mas sys.executable mostra diretamente que interpretador o comando python atual invoca. A desativação é reversível: altera o contexto ativo do terminal, não os ficheiros guardados no projeto. Depois de identificar a etapa que falhou, utilize o comando de ativação correspondente ao sistema operativo e à shell, em vez de copiar um comando destinado a outro terminal.

Um ambiente virtual é uma ferramenta local de isolamento, não um ficheiro de especificação do projeto. Se outra pessoa precisar de reconstruir o conjunto de pacotes, registe as dependências num ficheiro gerido pelo projeto. Para projetos simples que utilizam pip, um fluxo comum é gerar uma lista com python -m pip freeze > requirements.txt e, noutro ambiente, instalá-la com python -m pip install -r requirements.txt. A lista reflete os pacotes instalados e as respetivas versões naquele momento; verifique se é adequada para partilhar e manter antes de a tratar como uma descrição completa do projeto.

Não inclua .venv no repositório: normalmente é um diretório local, potencialmente grande e associado ao sistema e ao interpretador de origem. Inclua, em vez disso, os ficheiros que descrevem o projeto e as suas dependências, de acordo com o fluxo de trabalho utilizado pela equipa. Ao clonar ou copiar o projeto para outro computador, crie um novo ambiente com a versão adequada do Python e instale aí as dependências registadas.

O isolamento de venv tem limites deliberados. Não é uma máquina virtual nem um contentor: não substitui a instalação do interpretador, não copia necessariamente todo o sistema operativo e não elimina diferenças entre plataformas. Além disso, como a instalação base permanece fora do ambiente, um ambiente virtual não substitui as práticas de segurança, atualização e gestão de versões. No uso quotidiano, o ciclo é simples: aceder ao projeto, criar .venv, ativá-lo, instalar as dependências, executar o programa e desativá-lo quando terminar.

O próprio ambiente não é o registo de que outra pessoa precisa para reproduzir o conjunto de pacotes do projeto. Um ficheiro de dependências fornece esse registo num formato que pode ser utilizado ao criar um ambiente novo. O comando freeze lista os pacotes instalados e as respetivas versões no momento em que é executado; por isso, o resultado deve ser revisto e mantido, em vez de se presumir que descreve todos os aspetos do projeto. Da mesma forma, excluir .venv do repositório evita tratar um diretório local como a descrição partilhada do projeto. Para recriar o ambiente noutro computador, escolha uma instalação de Python adequada e instale aí as dependências. Assim, os ficheiros do projeto, os registos das dependências e o ambiente local utilizado para executar o projeto permanecem distintos. O processo também reforça o limite essencial: o isolamento de pacotes é útil, mas não torna computadores ou sistemas operativos diferentes idênticos.