Ambiente Virtual — Python — Lucilia's Notebook

O problema que o ambiente virtual resolve

Imagine essa situação

Você tem dois projetos no computador. O Projeto A usa Flask na versão 2.0. O Projeto B usa Flask na versão 3.0 — porque precisa de um recurso novo que só existe nessa versão. Se você instalar os dois no mesmo Python do seu computador, um vai sobrescrever o outro. Um dos projetos vai quebrar.

Agora imagina que você tem 10 projetos, cada um com versões diferentes de bibliotecas diferentes. Seria um caos total. É exatamente esse problema que o ambiente virtual resolve.

Analogia — cada projeto é uma cozinha separada

Pensa assim: o Python instalado no seu computador é como um supermercado. As bibliotecas são os ingredientes. Sem ambiente virtual, todos os seus projetos compartilham a mesma despensa — e quando você muda um ingrediente para um projeto, pode estragar a receita de outro.

O ambiente virtual é como dar para cada projeto a sua própria cozinha, com a sua própria despensa. O Projeto A tem a sua versão do Flask. O Projeto B tem a dele. Nenhum interfere no outro. Cada cozinha é independente — mesmo que todas usem ingredientes vindos do mesmo supermercado.

❌ Sem ambiente virtual

💥Projetos compartilham as mesmas bibliotecas

💥Atualizar uma lib pode quebrar outro projeto

💥Impossível ter versões diferentes da mesma lib

💥Difícil saber quais libs o projeto realmente usa

💥"Funciona na minha máquina" — mas não na do colega

✅ Com ambiente virtual

✅Cada projeto tem seu próprio espaço isolado

✅Atualizar libs de um projeto não afeta os outros

✅Versões diferentes da mesma lib em projetos diferentes

✅Lista exata de dependências fácil de exportar

✅Qualquer pessoa reproduz o mesmo ambiente

O que é um ambiente virtual?

Uma cópia isolada do Python para o seu projeto

Um ambiente virtual (virtual environment, ou venv) é uma pasta que contém uma cópia funcional do Python e um espaço isolado para instalar bibliotecas. Quando você "ativa" o ambiente, o sistema passa a usar o Python dessa pasta — e todas as instalações com pip install vão para dentro dela, não para o Python global do computador.

Quando você desativa, tudo volta ao normal. O Python global não sabe nem que o ambiente virtual existe.

O que tem dentro de um venv?

Ao criar um ambiente virtual, o Python gera uma estrutura de pastas assim:

venv/
├── bin/         ← Linux/Mac
│   ├── python     ← link para o Python do venv
│   ├── pip        ← pip do venv (instala aqui dentro)
│   └── activate   ← script que ativa o ambiente
├── Scripts/     ← Windows (equivalente ao bin/)
├── lib/
│   └── python3.x/
│       └── site-packages/ ← suas libs instaladas ficam aqui
└── pyvenv.cfg   ← configuração do venv

Você nunca edita esses arquivos manualmente

A pasta venv/ é gerada e gerenciada automaticamente. Você não precisa mexer dentro dela. Basta criar, ativar, instalar libs com pip e trabalhar normalmente.

Como funciona por dentro

O que muda quando você ativa o venv?

Quando você executa o script activate, ele faz uma coisa simples mas poderosa: modifica temporariamente as variáveis de ambiente do seu terminal, especialmente o PATH. O PATH é a lista de pastas onde o sistema operacional procura comandos. O activate coloca a pasta bin/ do seu venv no início dessa lista.

A partir daí, quando você digita python ou pip, o sistema encontra primeiro o Python e o pip do seu venv — não os globais. É só isso. Uma mudança de PATH. Quando você desativa (deactivate), o PATH volta ao normal.

1

Antes de ativar — Python global O terminal usa o Python instalado no sistema. which python retorna algo como /usr/bin/python3. O pip instala libs no Python global.

2

Você roda: source venv/bin/activate O script modifica o PATH do terminal, colocando venv/bin/ na frente. O nome do ambiente aparece entre parênteses no prompt: (venv) $.

3

Agora — Python isolado which python retorna ./venv/bin/python. Qualquer pip install instala dentro de venv/lib/site-packages/. Nada vai para o Python global.

4

Você roda: deactivate O PATH volta ao estado original. O prompt some o (venv). O Python global volta a ser o padrão. O venv continua existindo na pasta — só foi "desligado".

✅ O venv não some quando você desativa

Desativar não apaga nada. As libs que você instalou continuam lá dentro. Da próxima vez que quiser usar o projeto, é só ativar de novo. O venv só some se você apagar a pasta manualmente.

pip — o instalador de pacotes Python

O que é o pip?

O pip é o gerenciador de pacotes oficial do Python. Ele se conecta ao PyPI (Python Package Index — o repositório público de bibliotecas Python) e baixa, instala, atualiza e remove pacotes para você. Com um único comando você instala qualquer uma das centenas de milhares de bibliotecas disponíveis.

Com o venv ativo, o pip instala tudo dentro do ambiente isolado. Sem venv ativo, ele instala no Python global — o que geralmente não é o que você quer.

Terminal — comandos essenciais do pip

# Instalar uma biblioteca
pip install flask

# Instalar uma versão específica
pip install flask==3.0.0

# Instalar a versão mínima
pip install flask>=2.0

# Atualizar uma biblioteca para a versão mais recente
pip install --upgrade flask

# Desinstalar
pip uninstall flask

# Listar tudo que está instalado no ambiente atual
pip list

# Ver detalhes de uma biblioteca específica
pip show flask

# Ver se há atualizações disponíveis
pip list --outdated

O que é o PyPI?

O PyPI (pypi.org) é o repositório central de bibliotecas Python — pensa nele como uma loja de apps, mas para código Python. Qualquer desenvolvedor pode publicar uma lib lá. O pip baixa de lá por padrão. Quando você faz pip install flask, o pip vai ao PyPI, encontra o pacote flask, baixa e instala no seu ambiente.

Criando e usando um venv na prática

1

Crie a pasta do projeto e entre nela

Terminal

mkdir meu_projeto
cd meu_projeto

2

Crie o ambiente virtual

O comando abaixo cria uma pasta chamada venv dentro do projeto com o Python e o pip isolados. Você pode nomear a pasta do jeito que quiser, mas venv é a convenção da comunidade.

Terminal

# Cria o ambiente virtual na pasta "venv"
python -m venv venv

# O "-m venv" chama o módulo venv que já vem com o Python 3
# Não precisa instalar nada!

3

Ative o ambiente virtual

O comando é diferente dependendo do sistema operacional e do terminal. Após ativar, o nome (venv) aparece no início do prompt — esse é o sinal de que está ativo.

Ativando — escolha o seu sistema

# Linux e Mac (bash/zsh)
source venv/bin/activate

# Windows — Prompt de Comando (cmd)
venv\Scripts\activate.bat

# Windows — PowerShell
venv\Scripts\Activate.ps1

# Após ativar, o prompt muda para:
(venv) $   # Linux/Mac
(venv) C:\meu_projeto>   # Windows

⚠️ Erro no PowerShell? Política de execução

Se o Windows bloquear o script com erro de "política de execução", rode este comando no PowerShell como administrador e tente ativar novamente: Set-ExecutionPolicy RemoteSigned

4

Confirme que está no ambiente certo

Terminal — verificando

# Mostra qual Python está sendo usado
which python       # Linux/Mac
where python       # Windows

# Deve mostrar o caminho dentro do venv:
# /home/usuario/meu_projeto/venv/bin/python

# Confirme a versão
python --version

5

Instale as bibliotecas do projeto

 Terminal — com o venv ativo
pip install flask
pip install requests
pip install sqlalchemy

# Tudo vai para venv/lib/site-packages/ — não para o Python global
          

6

Desative quando terminar

 Terminal
deactivate

# O (venv) some do prompt — voltou ao Python global
          

✅ Resumo rápido para usar todo dia

Criar: python -m venv venv — só uma vez por projeto.
Ativar: source venv/bin/activate — toda vez que abrir o terminal para trabalhar no projeto.
Instalar: pip install nome-da-lib — com o venv ativo.
Desativar: deactivate — quando terminar.

requirements.txt — compartilhando dependências

Como contar para os outros o que seu projeto precisa?

A pasta venv/ não vai para o Git — ela é grande, gerada automaticamente e específica para cada máquina. Mas e quando outra pessoa quiser rodar seu projeto? Como ela vai saber quais bibliotecas instalar, e em quais versões?

A resposta é o arquivo requirements.txt. Ele é uma lista simples com o nome e a versão de cada biblioteca que o projeto usa. Com ele, qualquer pessoa consegue recriar exatamente o mesmo ambiente com um único comando.

Gerando o requirements.txt

 Terminal — com o venv ativo
# Gera o arquivo com todas as libs instaladas e suas versões exatas
pip freeze > requirements.txt

# Veja o que foi gerado:
cat requirements.txt
    

 requirements.txt — exemplo de conteúdo
blinker==1.8.2
click==8.1.7
Flask==3.0.3
itsdangerous==2.2.0
Jinja2==3.1.4
MarkupSafe==2.1.5
Werkzeug==3.0.3
    

Instalando a partir do requirements.txt

 Terminal — em uma máquina nova
# 1. Clone o projeto (ou receba os arquivos)
# 2. Crie e ative o venv
python -m venv venv
source venv/bin/activate

# 3. Instale tudo de uma vez a partir do arquivo
pip install -r requirements.txt

# Pronto! O ambiente está idêntico ao original.
    

✅ Atualize o requirements.txt sempre que instalar algo novo

Toda vez que instalar uma biblioteca nova no projeto, rode pip freeze > requirements.txt de novo para manter o arquivo atualizado. É um hábito simples que evita muita dor de cabeça no futuro.

🔒 Com versões fixas (`==`)

O pip freeze usa == para fixar a versão exata. É mais seguro — garante que todos usem exatamente o mesmo ambiente.

🔓 Com versões flexíveis (`>=`)

Você pode editar o arquivo manualmente e usar flask>=2.0 para aceitar qualquer versão 2.0+. Útil em bibliotecas que você quer manter atualizadas.

.gitignore — o que não deve ir para o Git

Por que não subir a pasta venv/ para o repositório?

A pasta venv/ pode ter centenas de megabytes e contém arquivos binários gerados especificamente para o sistema operacional e a versão do Python da sua máquina. Ela não funciona na máquina de outra pessoa se for copiada. E é completamente desnecessário — qualquer um pode recriar com pip install -r requirements.txt.

Por isso, a pasta venv/ vai no .gitignore: um arquivo que diz ao Git quais arquivos e pastas ignorar completamente.

.gitignore — mínimo para projetos Python

# Ambiente virtual — nunca sobe para o Git venv/ .venv/ env/ # Arquivos compilados Python __pycache__/ *.py[cod] *.pyo # Variáveis de ambiente e segredos .env *.env # Configurações de editores .vscode/ .idea/ *.DS_Store # Logs e bancos de dados locais *.log *.sqlite3 db.sqlite3

Nunca suba o arquivo .env para o Git

O arquivo .env contém senhas, chaves de API e dados sensíveis. Se for para o GitHub, qualquer pessoa no mundo pode ver. Sempre coloque .env no .gitignore. Para compartilhar quais variáveis existem (sem os valores), crie um .env.example com valores fictícios — esse sim pode ir para o repositório.

Como fica a estrutura ideal de um projeto

meu_projeto/
├── venv/               ← NÃO vai pro Git
├── .env                ← NÃO vai pro Git (senhas!)
├── .env.example      ← vai pro Git (valores fictícios)
├── .gitignore        ← vai pro Git
├── requirements.txt ← vai pro Git
├── app.py            ← vai pro Git
└── templates/        ← vai pro Git

Fluxo completo — do zero ao projeto funcionando

O ritual que você vai repetir em todo projeto Python

Com o tempo, criar e configurar um ambiente virtual vai se tornar automático — como escovar os dentes. Aqui está o fluxo completo que você deve seguir em todo projeto novo.

 Terminal — fluxo completo de um projeto novo
# ── CRIANDO O PROJETO ────────────────────────────────────
mkdir meu_projeto && cd meu_projeto

# Criar o venv
python -m venv venv

# Ativar (Linux/Mac)
source venv/bin/activate

# Criar o .gitignore imediatamente
echo "venv/" > .gitignore
echo ".env"  >> .gitignore
echo "__pycache__/" >> .gitignore

# Criar o .env para variáveis de ambiente
touch .env

# ── INSTALANDO DEPENDÊNCIAS ──────────────────────────────
pip install flask
pip install python-dotenv

# Salvar as dependências
pip freeze > requirements.txt

# ── TRABALHANDO NO PROJETO ──────────────────────────────
# (escreva seu código aqui)

# ── SUBINDO PARA O GIT ──────────────────────────────────
git init
git add .
git commit -m "primeiro commit"

# venv/ e .env não vão — o .gitignore cuida disso
    

 Terminal — fluxo de quem clonou o projeto
# Clonou o projeto do GitHub
git clone https://github.com/usuario/meu_projeto
cd meu_projeto

# Criar o próprio venv local
python -m venv venv
source venv/bin/activate

# Instalar todas as dependências de uma vez
pip install -r requirements.txt

# Copiar o .env.example e preencher com os valores reais
cp .env.example .env
# (edite o .env com suas credenciais)

# Rodar o projeto
python app.py
    

Outras ferramentas — pipenv e poetry

O venv não é a única opção

O venv + pip é a dupla padrão que vem com o Python e funciona muito bem. Mas existem ferramentas mais modernas que combinam a criação do ambiente, gerenciamento de dependências e outras funcionalidades numa coisa só.

Ferramenta	O que faz diferente	Quando usar
`venv + pip`	Padrão — já vem com Python 3, sem instalação extra	Qualquer projeto — é o ponto de partida ideal
`pipenv`	Combina venv e pip. Usa `Pipfile` em vez de requirements.txt. Separa dependências de dev e produção automaticamente	Projetos pequenos/médios onde você quer mais conforto que o pip
`poetry`	Gerencia dependências, venv, versões e publicação de pacotes. Arquivo `pyproject.toml`. Mais moderno e poderoso	Projetos maiores, libs que você vai publicar no PyPI
`conda`	Gerenciador de ambientes da Anaconda. Suporte a Python e outras linguagens. Muito usado em ciência de dados	Data science, machine learning, quando você usa Jupyter Notebooks

Por onde começar?

Aprenda bem o venv + pip primeiro. Eles são o padrão da comunidade, estão em todos os tutoriais e funcionam em qualquer ambiente. Quando você se sentir confortável, explore o Poetry — é a ferramenta mais moderna e adotada atualmente para projetos profissionais.

Referência rápida — comandos do dia a dia

O que fazer	Linux / Mac	Windows
Criar venv	`python -m venv venv`	`python -m venv venv`
Ativar	`source venv/bin/activate`	`venv\Scripts\activate`
Desativar	`deactivate`	`deactivate`
Instalar lib	`pip install flask`	`pip install flask`
Listar libs	`pip list`	`pip list`
Exportar dependências	`pip freeze > requirements.txt`	`pip freeze > requirements.txt`
Instalar dependências	`pip install -r requirements.txt`	`pip install -r requirements.txt`
Confirmar Python ativo	`which python`	`where python`
Apagar o venv	`rm -rf venv/`	`rmdir /s venv`