Ambientes Virtuais Python: venv, uv e Poetry em 2026

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, atualizado para 2026, a gente vai explorar as ferramentas mais usadas: venv (o padrão que já vem no Python), virtualenv, Poetry e o uv, que virou a referência para projetos novos. Para comparar gerenciadores de pacotes no geral, vale conferir também o nosso pip vs uv vs Poetry vs Conda e o guia passo a passo de como criar um virtual environment.

Resposta rápida

Para criar um ambiente virtual em Python, rode python -m venv .venv e ative com source .venv/bin/activate (Linux/macOS) ou .venv\Scripts\Activate.ps1 (Windows PowerShell). O .venv é a pasta isolada onde as dependências do projeto ficam separadas do Python do sistema, evitando conflitos de versão entre projetos.

Na comparação venv vs uv vs Poetry, use venv + pip quando quiser a opção nativa e mais simples; escolha uv em projetos novos quando quiser ambiente, dependências, lockfile e execução em uma ferramenta rápida; mantenha Poetry quando a equipe já padronizou seu fluxo, publica pacotes com ele ou depende de suas convenções. venv cria o isolamento, mas não substitui um gerenciador de dependências. uv e Poetry cobrem as duas responsabilidades.

A escolha não muda o formato do ambiente: as ferramentas normalmente criam uma pasta .venv que editores como VS Code e PyCharm conseguem detectar. O que muda é quem resolve e registra as dependências. Com venv, você combina o ambiente com pip e requirements.txt; com uv ou Poetry, o projeto passa a usar pyproject.toml e um lockfile reproduzível.

Comandos equivalentes: venv, uv e Poetry

Este é o mesmo fluxo — criar o ambiente, adicionar o pacote requests e executar o programa — nas três opções:

Se a dúvida é especificamente “venv ou uv?”, não é necessário migrar tudo de uma vez. Você pode criar o ambiente com uv venv e continuar instalando um requirements.txt com uv pip install -r requirements.txt. Se a dúvida é “venv ou Poetry?”, observe o repositório: a presença de poetry.lock e seções do Poetry no pyproject.toml é um sinal claro para usar Poetry naquele projeto.

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

# 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

# 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

# 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

# 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

# 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

#!/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()

Editores e ambientes virtuais

Editores modernos detectam e ativam o .venv automaticamente, mas vale saber onde configurar isso manualmente:

• VS Code para Python: o VS Code encontra a pasta .venv sozinho. Para forçar, abra a paleta de comandos (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS), escolha Python: Select Interpreter e selecione .venv/bin/python. O terminal integrado ativa o ambiente ao abrir.
• PyCharm: em File > Settings > Project > Python Interpreter, crie ou selecione o ambiente virtual. O PyCharm ativa o .venv em todos os terminais e configurações de execução.
• Linters e formatadores (ruff, black, mypy): eles rodam dentro do ambiente ativo, por isso o .venv precisa estar selecionado. Veja como integrá-los no guia de linters e formatação em Python.

Manter o .venv dentro do projeto (com virtualenvs.in-project true no Poetry, ou o padrão do uv venv) é o que faz os editores encontrarem o ambiente sem configuração extra.

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.

# 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 é uma ferramenta madura e completa para gerenciamento de dependências em Python. Ele resolve dependências automaticamente, gera lockfiles e gerencia o ambiente virtual para você. Em projetos novos, o uv costuma oferecer um fluxo mais rápido; em bases que já usam poetry.lock, continuar com Poetry normalmente é a decisão de menor risco.

Instalação do Poetry

Para um passo a passo detalhado de instalação e configuração (inclusive deixando o ambiente dentro do projeto com virtualenvs.in-project true), veja o guia de como configurar o Poetry.

# 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

# 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:

# pyproject.toml
# [tool.poetry]
# name = "meu-projeto"
# version = "0.1.0"
# description = "Um projeto Python incrível"
# authors = ["Maria Silva <[email protected]>"]
# 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

# 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

# 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:

# 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

uv: o padrão de 2026

O uv é um gerenciador de pacotes e ambientes virtuais escrito em Rust pela Astral (a mesma equipe do Ruff). Em 2026 ele virou a escolha padrão para muitos projetos novos porque é 10 a 100 vezes mais rápido que o pip e unifica em uma só ferramenta a criação do ambiente, a instalação de pacotes, o lockfile e até o gerenciamento de versões do Python. Se você está começando um projeto agora, vale considerar o uv desde o início.

Criando um ambiente virtual com uv

# Criar um ambiente virtual na pasta .venv (padrão recomendado)
uv venv

# Criar com uma versão específica do Python
uv venv --python 3.12

# Ativar (igual ao venv tradicional)
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\Activate.ps1       # Windows (PowerShell)

O uv venv cria o mesmo tipo de ambiente que o python -m venv, mas em frações de segundo. A ativação é idêntica, então tudo que você já sabe sobre .venv/bin/activate continua valendo.

Instalando pacotes com uv

# Instalar pacotes dentro do ambiente ativo
uv pip install flask requests pandas

# Instalar a partir de um requirements.txt
uv pip install -r requirements.txt

# Exportar dependências instaladas
uv pip freeze > requirements.txt

# Remover um pacote
uv pip uninstall flask

O subcomando uv pip é compatível com o pip tradicional, então migrar é direto: troque pip por uv pip e ganhe velocidade sem mudar o fluxo.

Projetos com pyproject.toml e uv sync

O uv também gerencia projetos de ponta a ponta usando pyproject.toml, parecido com o Poetry:

# Iniciar um novo projeto (cria pyproject.toml, .venv e estrutura)
uv init meu-projeto && cd meu-projeto

# Adicionar dependências (atualiza pyproject.toml e uv.lock)
uv add flask sqlalchemy pydantic

# Adicionar dependência de desenvolvimento
uv add --dev pytest ruff mypy

# Instalar tudo do lock (reproduzível em qualquer máquina ou CI)
uv sync

# Rodar um comando dentro do ambiente, sem precisar ativar
uv run python app.py
uv run pytest

O uv.lock garante versões idênticas entre desenvolvimento, CI e produção — o mesmo objetivo do poetry.lock. A grande diferença é a velocidade: resolver e instalar um projeto grande costuma levar segundos, não minutos.

Quando escolher uv

• Projeto novo em 2026: o uv é a aposta mais moderna e rápida.
• Migrar de pip/requirements.txt: comece com uv pip e evolua para uv sync quando quiser lockfile.
• Times que já usam Poetry: não há urgência em migrar; o Poetry segue maduro e estável, e o uv interopera com pyproject.toml.

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

Erros comuns (e como resolver)

• python3: command not found ao criar o venv: no Windows, use python em vez de python3. No Linux (Ubuntu/Debian), instale o pacote com sudo apt install python3-venv.
• activate não roda no PowerShell: o Windows bloqueia scripts por padrão. Libere com Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser e rode .venv\Scripts\Activate.ps1 novamente.
• Bibliotecas “somem” depois de instalar: você instalou com o ambiente desativado. Confirme com which python (Linux/macOS) ou where python (Windows) — o caminho precisa apontar para dentro de .venv/.
• pip install diz que o pacote existe, mas import falha: há dois ambientes na jogada. Ative o .venv correto e rode pip list para ver onde o pacote realmente está.
• Versão errada do Python no venv: crie apontando o interpretador, por exemplo python3.12 -m venv .venv. Para alternar versões por projeto sem mexer no sistema, combine com o pyenv (seção mais abaixo) ou use uv venv --python 3.12.
• Docker x venv: dentro do contêiner o isolamento já vem da imagem, então o .venv é redundante. No desenvolvimento local (fora do Docker), ele continua necessário para não misturar dependências de projetos diferentes — veja o guia de Docker com Python para o fluxo completo.

Boas Práticas

# 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

# 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

Próximos passos e conteúdos relacionados

O ambiente virtual é o ponto de partida de qualquer projeto Python bem configurado. Depois de criar o seu, estes conteúdos ajudam a montar o resto do ambiente de desenvolvimento:

• Instalar o Python na sua máquina: Windows, macOS e Linux.
• Configurar o editor: VS Code para Python ou PyCharm.
• Gerenciar pacotes com profundidade: comparativo pip vs uv vs Poetry vs Conda e o guia dedicado ao uv.
• Configurar o Poetry do zero: passo a passo em como configurar o Poetry.
• Linters e formatadores: ruff, black e mypy integrados.
• Data science: configurar o Jupyter Notebook.
• Ambiente com Docker: Docker e Python para quando o contêiner substitui o venv.

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 novo em 2026: Use uv — rápido, unifica ambiente, pacotes, lockfile e versões do Python
• Equipe que já padronizou em Poetry: continue com Poetry — gerenciamento completo, grupos de dependências e publicação de pacotes
• 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. Para a comparação completa de gerenciadores, confira o nosso pip vs uv vs Poetry vs Conda.

Outras linguagens resolvem isolamento de forma nativa — Go com Go Modules e Rust com Cargo já isolam dependências por projeto sem necessidade de ambientes virtuais separados.