---
title: "Ambientes Virtuais Python: venv e Poetry"
url: "https://python.dev.br/blog/virtual-environments-python/"
markdown_url: "https://python.dev.br/blog/virtual-environments-python.MD"
description: "Guia completo sobre ambientes virtuais em Python: venv, virtualenv e Poetry. Aprenda a isolar dependências e gerenciar projetos profissionalmente."
date: "2025-09-12"
author: "Equipe Python Brasil"
---

# Ambientes Virtuais Python: venv e Poetry

Guia completo sobre ambientes virtuais em Python: venv, virtualenv e Poetry. Aprenda a isolar dependências e gerenciar projetos profissionalmente.


Se você já teve problemas com versões conflitantes de bibliotecas em Python, sabe a dor de cabeça que isso causa. **Ambientes virtuais** resolvem esse problema isolando as dependências de cada projeto. Neste guia, a gente vai explorar as três ferramentas mais populares: **venv**, **virtualenv** e **Poetry**.

## Por que Usar Ambientes Virtuais?

Sem ambientes virtuais, todas as bibliotecas são instaladas globalmente no sistema. Isso causa problemas quando:

- O **Projeto A** precisa de Django 4.2 e o **Projeto B** precisa de Django 5.0
- Uma atualização de biblioteca quebra outro projeto
- Você não sabe quais dependências seu projeto realmente precisa
- Você precisa reproduzir o ambiente em outra máquina ou no servidor

```python
# Exemplo do problema (sem ambiente virtual):
# pip install django==4.2  <- Projeto A precisa dessa versão
# pip install django==5.0  <- Projeto B sobrescreve! Projeto A quebra!

# Com ambientes virtuais, cada projeto tem suas próprias dependências
# isoladas, sem interferir um no outro.
```

## venv: O Padrão do Python

`venv` já vem incluído no Python 3.3+ e é a forma mais simples de criar ambientes virtuais.

### Criando e ativando

```python
# Criar o ambiente virtual
# python -m venv .venv

# Ativar no Linux/macOS
# source .venv/bin/activate

# Ativar no Windows (CMD)
# .venv\Scripts\activate

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

# Quando ativado, o prompt muda:
# (.venv) usuario@maquina:~/projeto$
```

### Usando o ambiente virtual

```python
# Instalar dependências (dentro do ambiente ativado)
# pip install flask requests pandas

# Ver pacotes instalados
# pip list

# Exportar dependências para requirements.txt
# pip freeze > requirements.txt

# Instalar a partir do requirements.txt (outra máquina)
# pip install -r requirements.txt

# Desativar o ambiente virtual
# deactivate
```

### Exemplo prático com venv

```python
# Fluxo completo de um projeto com venv

# 1. Criar o projeto
# mkdir meu-projeto && cd meu-projeto

# 2. Criar o ambiente virtual
# python -m venv .venv

# 3. Ativar
# source .venv/bin/activate  (Linux/macOS)

# 4. Instalar dependências
# pip install flask sqlalchemy python-dotenv

# 5. Gerar requirements.txt
# pip freeze > requirements.txt

# 6. Adicionar .venv ao .gitignore
# echo ".venv/" >> .gitignore
```

### Arquivo requirements.txt

```python
# requirements.txt - gerado com pip freeze
# Flask==3.0.2
# SQLAlchemy==2.0.27
# python-dotenv==1.0.1
# Werkzeug==3.0.1
# Jinja2==3.1.3

# Você também pode ter um requirements-dev.txt para desenvolvimento:
# -r requirements.txt
# pytest==8.0.0
# pytest-cov==4.1.0
# black==24.1.0
# flake8==7.0.0
```

### Script para automatizar setup com venv

```python
#!/usr/bin/env python3
"""Script para configurar o ambiente de desenvolvimento."""

import subprocess
import sys
import os
from pathlib import Path

def setup_projeto():
    projeto_dir = Path(".")
    venv_dir = projeto_dir / ".venv"

    # Criar venv se não existir
    if not venv_dir.exists():
        print("Criando ambiente virtual...")
        subprocess.run([sys.executable, "-m", "venv", str(venv_dir)])
        print("Ambiente virtual criado!")

    # Determinar o pip do venv
    if os.name == "nt":  # Windows
        pip = str(venv_dir / "Scripts" / "pip")
    else:  # Linux/macOS
        pip = str(venv_dir / "bin" / "pip")

    # Atualizar pip
    print("Atualizando pip...")
    subprocess.run([pip, "install", "--upgrade", "pip"])

    # Instalar dependências
    requirements = projeto_dir / "requirements.txt"
    if requirements.exists():
        print("Instalando dependências...")
        subprocess.run([pip, "install", "-r", str(requirements)])
    else:
        print("requirements.txt não encontrado.")

    # Instalar dependências de desenvolvimento
    requirements_dev = projeto_dir / "requirements-dev.txt"
    if requirements_dev.exists():
        print("Instalando dependências de desenvolvimento...")
        subprocess.run([pip, "install", "-r", str(requirements_dev)])

    print("\nSetup concluído!")
    print(f"Ative o ambiente com: source {venv_dir}/bin/activate")

if __name__ == "__main__":
    setup_projeto()
```

## virtualenv: A Alternativa Clássica

`virtualenv` é mais antigo que `venv` e tem algumas vantagens como ser mais rápido e suportar versões mais antigas de Python.

```python
# Instalação
# pip install virtualenv

# Criar ambiente virtual
# virtualenv .venv

# Criar com versão específica de Python
# virtualenv -p python3.11 .venv

# Ativar (mesmo que venv)
# source .venv/bin/activate

# virtualenv cria ambientes mais rápido que venv
# e tem opção de --copies e --clear
```

## Poetry: Gerenciamento Moderno

**Poetry** é a ferramenta mais moderna e completa para gerenciamento de dependências em Python. Ele resolve dependências automaticamente, gera lock files e gerencia o ambiente virtual pra você.

### Instalação do Poetry

```python
# Instalação recomendada (Linux/macOS)
# curl -sSL https://install.python-poetry.org | python3 -

# Verificar instalação
# poetry --version

# Configurar para criar .venv dentro do projeto
# poetry config virtualenvs.in-project true
```

### Criando um projeto com Poetry

```python
# Criar novo projeto
# poetry new meu-projeto

# Estrutura criada:
# meu-projeto/
# ├── pyproject.toml
# ├── README.md
# ├── meu_projeto/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

# Ou inicializar em projeto existente
# cd meu-projeto-existente
# poetry init
```

### pyproject.toml

O `pyproject.toml` é o coração do Poetry — ele substitui `setup.py`, `requirements.txt` e `setup.cfg`:

```python
# pyproject.toml
# [tool.poetry]
# name = "meu-projeto"
# version = "0.1.0"
# description = "Um projeto Python incrível"
# authors = ["Maria Silva <maria@email.com>"]
# readme = "README.md"
# python = "^3.10"
#
# [tool.poetry.dependencies]
# python = "^3.10"
# flask = "^3.0"
# sqlalchemy = "^2.0"
# pydantic = "^2.5"
#
# [tool.poetry.group.dev.dependencies]
# pytest = "^8.0"
# pytest-cov = "^4.1"
# black = "^24.0"
# ruff = "^0.2"
# mypy = "^1.8"
#
# [build-system]
# requires = ["poetry-core"]
# build-backend = "poetry.core.masonry.api"
```

### Comandos Essenciais do Poetry

```python
# Adicionar dependências
# poetry add flask
# poetry add sqlalchemy pydantic
# poetry add "django>=4.2,<5.0"

# Adicionar dependência de desenvolvimento
# poetry add --group dev pytest black ruff

# Remover dependência
# poetry remove flask

# Instalar todas as dependências
# poetry install

# Instalar sem dependências de dev (produção)
# poetry install --without dev

# Atualizar dependências
# poetry update
# poetry update flask  # atualizar pacote específico

# Ver dependências instaladas
# poetry show
# poetry show --tree  # em formato de árvore

# Rodar comandos dentro do ambiente virtual
# poetry run python meu_script.py
# poetry run pytest
# poetry run flask run

# Ativar o shell do ambiente virtual
# poetry shell
```

### Exemplo prático com Poetry

```python
# Fluxo completo de um projeto Flask com Poetry

# 1. Criar projeto
# poetry new minha-api && cd minha-api

# 2. Adicionar dependências
# poetry add flask flask-sqlalchemy python-dotenv

# 3. Adicionar dependências de dev
# poetry add --group dev pytest pytest-cov black ruff

# 4. Criar o app
# minha_api/app.py
from flask import Flask, jsonify

def create_app():
    app = Flask(__name__)

    @app.route("/")
    def index():
        return jsonify({"status": "online", "mensagem": "API funcionando!"})

    @app.route("/saude")
    def health_check():
        return jsonify({"status": "saudável"})

    return app

if __name__ == "__main__":
    app = create_app()
    app.run(debug=True)
```

### Poetry Lock File

O `poetry.lock` garante que todos os desenvolvedores e o servidor de produção usem exatamente as mesmas versões:

```python
# O poetry.lock é gerado automaticamente e deve ser commitado no git!
# Ele contém as versões exatas de todas as dependências e sub-dependências.

# Para instalar exatamente as versões do lock:
# poetry install

# Para atualizar o lock sem instalar:
# poetry lock

# Para verificar se o lock está atualizado:
# poetry check
```

## Comparação: venv vs virtualenv vs Poetry

| Aspecto | venv | virtualenv | Poetry |
|---------|------|------------|--------|
| Instalação | Incluso no Python | pip install | Instalador próprio |
| Resolução de deps | Manual (pip) | Manual (pip) | Automática |
| Lock file | Não | Não | Sim (poetry.lock) |
| Grupos de deps | Não | Não | Sim (dev, test, etc.) |
| Publicar pacote | Não | Não | Sim |
| Scripts | Não | Não | Sim |
| Velocidade setup | Médio | Rápido | Médio |
| Curva aprendizado | Baixa | Baixa | Média |

## Boas Práticas

```python
# 1. SEMPRE use ambientes virtuais - sem exceção!

# 2. Adicione o diretório do venv ao .gitignore
# .gitignore
# .venv/
# __pycache__/
# *.pyc
# .env

# 3. Documente como configurar o ambiente
# No README.md ou CONTRIBUTING.md do seu projeto

# 4. Use nomes consistentes para o ambiente
# .venv (recomendado - fica oculto e dentro do projeto)

# 5. Trave as versões em produção
# Em vez de flask>=3.0, use flask==3.0.2 em produção

# 6. Separe dependências de dev e produção
# requirements.txt para produção
# requirements-dev.txt para desenvolvimento
# Ou use grupos do Poetry

# 7. Atualize dependências regularmente
# Mas teste tudo depois de atualizar!
```

## Dica Extra: pyenv para Gerenciar Versões do Python

```python
# pyenv permite instalar e alternar entre versões do Python

# Instalação (Linux/macOS)
# curl https://pyenv.run | bash

# Listar versões disponíveis
# pyenv install --list

# Instalar uma versão
# pyenv install 3.12.1

# Definir versão global
# pyenv global 3.12.1

# Definir versão por projeto
# cd meu-projeto
# pyenv local 3.11.7

# Combinação perfeita: pyenv + Poetry
# pyenv install 3.12.1
# pyenv local 3.12.1
# poetry env use python3.12
# poetry install
```

## Conclusão

A escolha entre as ferramentas depende do seu contexto:

- **Iniciante ou projeto simples**: Use `venv` — já vem com Python e é fácil de usar
- **Projeto profissional/equipe**: Use **Poetry** — gerenciamento completo e reproduzível
- **Compatibilidade com Python antigo**: Use `virtualenv`

O mais importante é **sempre usar algum tipo de isolamento**. Instalar pacotes globalmente é receita para dor de cabeça. Escolha a ferramenta que faz mais sentido pro seu projeto e use-a consistentemente.

Outras linguagens resolvem isolamento de forma nativa — <a href="https://golang.com.br/" target="_blank" rel="noopener" onclick="umami.track('portfolio-site-click', { destination: 'golang.com.br' })">Go com Go Modules</a> e <a href="https://rustlang.com.br/" target="_blank" rel="noopener" onclick="umami.track('portfolio-site-click', { destination: 'rustlang.com.br' })">Rust com Cargo</a> já isolam dependências por projeto sem necessidade de ambientes virtuais separados.