Ambientes virtuais em Python: venv, ativação e requirements.txt

O problema que ambientes virtuais resolvem

Instale o Python, rode pip install requests, e o pacote cai num único lugar global. Funciona bem para um projeto. No terceiro projeto, começa a doer:

• Projeto A precisa de django==3.2. Projeto B precisa de django==5.0. Só um deles pode ter sua versão instalada globalmente.
• Você quer testar uma biblioteca nova mas não quer poluir todos os outros projetos da sua máquina.
• Um colega de equipe clona seu repo e não faz ideia de quais versões de quais pacotes você de fato usou.

Um ambiente virtual é a correção. É uma pasta autocontida segurando um interpretador Python e seu próprio diretório de instalação de bibliotecas. Quando o ambiente está ativado, python e pip no seu terminal apontam para dentro daquela pasta em vez do seu Python do sistema. Pacotes instalados lá ficam lá.

Criando um com venv

venv vem com o Python 3 — nada para instalar. De dentro do seu diretório de projeto:

python3 -m venv .venv

Isso cria uma pasta .venv/ ao lado do seu código. O nome .venv é convenção quase universal; o ponto no começo mantém fora da maioria das listagens de diretório, e editores como VS Code detectam automaticamente.

Depois que o comando termina, a pasta contém uma instalação Python completa (dezenas de megabytes, o que é normal) e um pip próprio.

Ativando o ambiente

Ativação reescreve o PATH do seu shell para que python e pip resolvam para os de dentro de .venv/. O comando depende da sua plataforma:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Seu prompt ganha um prefixo (.venv) enquanto o ambiente está ativo — um lembrete visual. Qualquer pip install que você rodar agora afeta só este projeto.

Quando terminar o dia, deactivate restaura o estado anterior:

deactivate

Você não precisa desativar antes de fechar o terminal — sair do shell é a mesma coisa.

Instalando pacotes

Com o ambiente ativo, instale o que precisa:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Cheque o que está instalado com pip list. Remova algo com pip uninstall requests.

Os pacotes instalados vivem sob .venv/lib/pythonX.Y/site-packages/. Você nunca edita aqueles na mão — pip gerencia o diretório.

Fixando dependências com requirements.txt

Seu projeto é reprodutível só se outros puderem instalar as mesmas versões que você usou. O jeito mais simples de capturar isso é requirements.txt:

pip freeze > requirements.txt

pip freeze imprime cada pacote instalado com a versão exata. Commit o arquivo no git.

Quando um colaborador (ou você no futuro numa máquina nova) clona o repo:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Três comandos e o ambiente deles bate com o seu.

Um setup de projeto comum

O fluxo completo, do começo ao fim:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

Adicione .venv ao seu .gitignore

Nunca comite a pasta .venv/. É específica de plataforma e reprodutível a partir do requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Commitar ia inchar o repo, quebrar em outras máquinas e vazar quaisquer binários específicos de SO que seu interpretador tem.

Qual versão do Python?

Por padrão, python3 -m venv .venv usa qualquer python3 que seu shell resolve. Se você tem vários Pythons instalados (digamos, 3.12 e 3.13), seja explícito sobre qual:

python3.13 -m venv .venv

Uma vez que o venv existe, o interpretador dele está fixado — rodar python dentro do venv ativado sempre usa aquela versão específica, mesmo se seu Python de sistema mudar.

Quando as coisas dão errado

Alguns sintomas comuns e correções:

• pip install funciona, mas meus imports falham. Você instalou contra o Python errado. Ative o venv antes do pip install e reconfira com which python (macOS/Linux) ou where python (Windows).
• "ModuleNotFoundError" depois de ativar. O venv foi criado sem certas bibliotecas, ou o pacote instalou num venv diferente. pip list mostra o que está de fato no atual.
• Script de ativação não encontrado no Windows. O PowerShell pode bloquear scripts não assinados. Rode Set-ExecutionPolicy -Scope CurrentUser RemoteSigned uma vez para permitir scripts locais.
• "No module named venv". Em algumas distros Linux, venv é um pacote separado. sudo apt install python3-venv no Debian/Ubuntu.

Além do venv: Poetry, uv, pipenv

Uma vez que você está confortável com venv + pip + requirements.txt, vai esbarrar em ferramentas que envolvem as mesmas ideias com ergonomia melhor:

• Poetry — gerencia venvs, dependências e packaging com um único pyproject.toml.
• uv — um substituto drop-in para pip muito rápido; lida com venvs também.
• pipenv — ferramenta mais antiga que popularizou o padrão "Pipfile + Pipfile.lock".

Todas são boas. Nenhuma é exigida para aprender. Fique confortável com o fluxo simples de venv primeiro; o resto são otimizações.

O que levar

• Todo projeto Python real ganha seu próprio ambiente virtual.
• Crie um com python3 -m venv .venv, ative, depois pip install à vontade.
• Fixe dependências com pip freeze > requirements.txt e commit o arquivo.
• Nunca commit a pasta .venv/ em si.
• Quando imports se comportam mal, confira qual Python está ativo primeiro.

Próxima: o padrão __main__

Com um projeto montado e pacotes instalados, um último idioma fecha este capítulo — o guard if __name__ == "__main__". Está em quase todo arquivo Python feito para ser executado como script, e é assunto da próxima página.