Ambientes Virtuais Python (venv)

Um ambiente virtual é um diretório autocontido que mantém uma cópia privada de um interpretador Python e sua própria pasta site-packages. Os pacotes instalados dentro de um ambiente virtual ficam completamente isolados do Python do sistema e de todos os outros ambientes na sua máquina — assim, dois projetos podem depender de versões diferentes da mesma biblioteca sem nunca conflitar.

Este capítulo aborda por que os ambientes virtuais são importantes, como criá-los e ativá-los com o módulo integrado venv, como gerenciar dependências com o pip, e o fluxo de trabalho diário que a maioria dos projetos Python segue.

Por que os ambientes virtuais são importantes

Imagine que você tem dois projetos na mesma máquina:

• Projeto A requer requests==2.28.0
• Projeto B requer requests==2.31.0

Se você instalar ambas as versões no ambiente Python global, o pip simplesmente sobrescreve a versão que instalou primeiro. Um dos projetos vai quebrar. Os ambientes virtuais resolvem isso dando a cada projeto seu próprio diretório site-packages isolado, de modo que ambas as versões coexistam sem interferir uma na outra.

Outros benefícios práticos:

Criando um ambiente virtual

Python 3.3 e versões posteriores incluem venv na biblioteca padrão — nenhuma instalação adicional é necessária.

python -m venv .venv

Isso cria um diretório .venv na sua pasta atual. O nome .venv é uma convenção comum (o ponto inicial o oculta em sistemas semelhantes ao Unix), mas você pode usar qualquer nome que quiser — env, venv, ou até mesmo um nome específico do projeto.

O que o venv cria dentro de .venv:

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

No Windows, o layout difere ligeiramente — bin/ é Scripts/ e os separadores de caminho são barras invertidas.

Escolhendo uma versão específica do Python

Se você tiver várias versões do Python instaladas, passe o interpretador explicitamente:

python3.11 -m venv .venv

Ou no Windows:

py -3.11 -m venv .venv

O arquivo pyvenv.cfg dentro do ambiente registra qual interpretador foi usado, de modo que o ambiente sempre seja executado com essa versão.

Ativando o ambiente

Criar o ambiente não o utiliza automaticamente. Você deve ativá-lo, o que adiciona o diretório bin/ do ambiente ao início do seu PATH para que python e pip resolvam para as cópias do ambiente.

macOS e Linux:

source .venv/bin/activate

Windows (Prompt de Comando):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Após a ativação, o prompt do shell geralmente mostra o nome do ambiente entre parênteses:

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Todo comando pip install executado enquanto o ambiente está ativo instala em .venv/lib/.../site-packages/, nunca no Python do sistema.

Desativando

Quando você terminar de trabalhar no projeto ou quiser mudar para um ambiente diferente:

deactivate

O prompt do shell volta ao normal e python resolve para o interpretador do sistema novamente.

Instalando pacotes dentro de um ambiente virtual

Com o ambiente ativo, use o pip normalmente:

pip install requests flask

Confirme que os pacotes foram instalados no lugar certo:

pip show requests

A linha Location: na saída deve apontar para o seu diretório .venv.

Verificando o que está instalado

pip list

Um ambiente recém-criado normalmente contém apenas pip e setuptools. Todo o resto que você vir é algo que você (ou um arquivo de requisitos) instalou explicitamente.

Salvando e restaurando dependências

Exportando um arquivo de requisitos

Depois que o seu ambiente estiver configurado, congele as versões exatas dos pacotes para que qualquer pessoa possa reproduzi-lo:

pip freeze > requirements.txt

Um requirements.txt típico tem a seguinte aparência:

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Faça commit do requirements.txt no controle de versão. Não faça commit do próprio diretório .venv — adicione-o ao .gitignore.

Restaurando a partir de um arquivo de requisitos

Em uma nova máquina ou em um clone recente:

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Isso recria um ambiente idêntico ao que você congelou.

Fluxo de trabalho padrão de projeto

A maioria dos projetos Python segue esta sequência:

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

O que adicionar ao .gitignore

Nunca faça commit do diretório do ambiente no controle de versão — ele contém binários compilados, é específico da plataforma e pode ter dezenas de megabytes. Adicione um destes padrões ao seu .gitignore:

# Virtual environment
.venv/
venv/
env/

Faça commit apenas do requirements.txt (ou pyproject.toml + requirements.txt). Isso é tudo que alguém precisa para reconstruir o ambiente do zero.

venv versus outras ferramentas

venv é a solução integrada e suficiente para a maioria dos casos de uso. Você também pode encontrar estas alternativas:

Para a maioria dos iniciantes e projetos simples, python -m venv é a escolha certa — ele vem com Python e não requer instalação adicional.

Erros comuns e soluções

"python: command not found" ao criar o ambiente

Em algumas distribuições Linux, Python 3 é invocado como python3, não python:

python3 -m venv .venv

PowerShell recusa executar o script de ativação

Por padrão, o Windows PowerShell bloqueia scripts não assinados. Habilite a execução de scripts para o usuário atual:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Em seguida, execute o script de ativação novamente.

Pacotes instalados mas import falha

Você provavelmente esqueceu de ativar o ambiente. Execute:

source .venv/bin/activate

Depois tente o import novamente. Você pode confirmar qual Python está ativo com which python (macOS/Linux) ou where python (Windows).

O ambiente referencia uma instalação Python deletada

Se você atualizar o Python e remover a versão antiga, os links do venv ficam quebrados. Basta recriar o ambiente:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tabela de referência rápida

Capítulos relacionados

• Python pip — o guia completo para instalar, atualizar e remover pacotes
• Módulos Python — entenda como o sistema de importação do Python funciona
• Pacotes Python — organize seu próprio código em pacotes instaláveis

Prática