---
title: "Virtualenv: O que É e Como Funciona | Python Brasil"
url: "https://python.dev.br/glossario/virtualenv/"
markdown_url: "https://python.dev.br/glossario/virtualenv.MD"
description: "Guia completo sobre ambientes virtuais Python: venv vs virtualenv vs conda, pyenv, integração com VS Code e PyCharm, e alternativas como Poetry."
date: "2025-06-18"
author: ""
---

# Virtualenv: O que É e Como Funciona | Python Brasil

Guia completo sobre ambientes virtuais Python: venv vs virtualenv vs conda, pyenv, integração com VS Code e PyCharm, e alternativas como Poetry.


## O que é Virtualenv?

O **virtualenv** (virtual environment) é uma ferramenta que cria **ambientes Python completamente isolados** para cada projeto. Dentro de um ambiente virtual, você tem uma cópia independente do interpretador Python e um diretório exclusivo para instalar pacotes — sem interferir no Python do sistema operacional nem nos outros projetos da sua máquina.

A partir do **Python 3.3**, o módulo `venv` foi incorporado à biblioteca padrão, tornando desnecessário instalar o virtualenv externamente na maioria dos casos. O `venv` é a solução oficial e recomendada para a maioria dos projetos.

## Por que o isolamento é fundamental

Imagine dois projetos reais coexistindo na mesma máquina:

- **Projeto A** (sistema legado): usa Django 3.2 com Python 3.8
- **Projeto B** (sistema novo): usa Django 4.2 com Python 3.11

Sem ambientes virtuais, instalar Django 4.2 quebraria o Projeto A, pois apenas uma versão do Django pode existir no Python global. Com ambientes virtuais, cada projeto vive no seu próprio mundo independente, com sua própria versão do Python e seus próprios pacotes.

Além disso, sem isolamento você pode inadvertidamente instalar centenas de pacotes no Python do sistema, tornando difícil saber quais são realmente necessários para cada projeto.

## Criando e ativando ambientes virtuais

```bash
# Criar um ambiente virtual com venv (nativo do Python 3)
python3 -m venv .venv

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

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

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

# Verificar que o ambiente está ativo
which python       # deve apontar para .venv/bin/python
python --version   # versão dentro do ambiente

# Desativar o ambiente
deactivate
```

Com o ambiente ativado, o terminal mostra o nome do ambiente entre parênteses:

```bash
(.venv) usuario@maquina:~/meu-projeto$
```

Todos os comandos `pip install` a partir daí instalam pacotes apenas dentro do ambiente.

## A convenção .venv

O nome `.venv` (com ponto, tornando-o um diretório oculto no Linux/macOS) é a convenção mais amplamente adotada atualmente, recomendada pela documentação oficial do Python e pelo PEP 8. Outras convenções comuns:

```bash
python3 -m venv .venv    # padrão mais comum (ponto torna oculto)
python3 -m venv venv     # alternativa sem ponto
python3 -m venv env      # também usada
```

Independentemente do nome escolhido, **sempre adicione ao `.gitignore`**:

```gitignore
# .gitignore
.venv/
venv/
env/
__pycache__/
*.pyc
```

Nunca versione o ambiente virtual no Git. Versione apenas o `requirements.txt` ou `pyproject.toml`.

## venv vs virtualenv vs conda

Existem três ferramentas principais para criar ambientes isolados em Python, cada uma com suas características:

```bash
# venv — padrão do Python 3, já incluído
python3 -m venv .venv
# Prós: sem instalação extra, padrão oficial
# Contras: não gerencia versões do Python

# virtualenv — biblioteca externa, mais recursos
pip install virtualenv
virtualenv .venv
virtualenv -p python3.11 .venv  # especifica versão do Python
# Prós: mais rápido, suporta Python 2, mais configurável
# Contras: instalação extra necessária

# conda — ecossistema Anaconda
conda create -n meu_projeto python=3.11
conda activate meu_projeto
# Prós: gerencia Python + pacotes binários (C/Fortran), multiplataforma
# Contras: mais pesado, ecossistema separado do PyPI
```

Para a maioria dos projetos Python modernos, o `venv` nativo é suficiente. O `conda` é preferido em projetos de ciência de dados que dependem de pacotes com compilação nativa complexa.

## Integração com pyenv

O **pyenv** é uma ferramenta para instalar e gerenciar múltiplas versões do Python na mesma máquina. Combinado com ambientes virtuais, oferece controle total:

```bash
# Instalar pyenv (macOS/Linux)
curl https://pyenv.run | bash

# Instalar uma versão específica do Python
pyenv install 3.11.7
pyenv install 3.12.1

# Definir versão global
pyenv global 3.12.1

# Definir versão local para um projeto (cria .python-version)
cd meu-projeto
pyenv local 3.11.7

# Criar ambiente virtual com a versão correta
python -m venv .venv   # usará o python 3.11.7 definido pelo pyenv
source .venv/bin/activate
```

O arquivo `.python-version` criado pelo pyenv deve ser versionado no Git, pois documenta qual versão do Python o projeto requer.

## Fluxo de trabalho completo

```bash
# 1. Criar e entrar no diretório do projeto
mkdir meu-projeto && cd meu-projeto

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

# 3. Ativar
source .venv/bin/activate

# 4. Atualizar o pip dentro do ambiente
pip install --upgrade pip

# 5. Instalar dependências
pip install django fastapi requests

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

# 7. Trabalhar no projeto...

# 8. Quando outro desenvolvedor clonar o projeto:
git clone https://github.com/usuario/meu-projeto.git
cd meu-projeto
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Integração com editores de código

**VS Code:** ao abrir um projeto com `.venv`, o VS Code detecta automaticamente o ambiente virtual e sugere usá-lo. Para selecionar manualmente, use `Ctrl+Shift+P` > "Python: Select Interpreter" e escolha `.venv/bin/python`. O arquivo `.vscode/settings.json` pode fixar o interpretador:

```json
{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true
}
```

**PyCharm:** ao criar um novo projeto, o PyCharm oferece opção de criar um virtualenv automaticamente. Para projetos existentes, vá em `Settings > Project > Python Interpreter > Add Interpreter > Virtualenv Environment`.

## Docker e ambientes virtuais

Em containers Docker, a questão é mais sutil. Como o container já é isolado, muitos projetos não usam virtualenv dentro do Docker. Porém, há situações onde o virtualenv dentro do Docker é útil:

```dockerfile
FROM python:3.12-slim

WORKDIR /app

# Criar virtualenv dentro do container
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "app.py"]
```

Isso evita que pacotes instalados em modo de sistema sejam mesclados com pacotes do projeto, e facilita multi-stage builds.

## Armadilhas comuns

```bash
# Armadilha 1: esquecer de ativar o ambiente
pip install django   # instala no Python do sistema!
# Solução: sempre verifique o prompt ou use "which python"

# Armadilha 2: versionar o ambiente virtual
git add .venv/       # NUNCA faça isso
# Solução: .gitignore correto desde o início do projeto

# Armadilha 3: copiar ou mover o ambiente virtual
mv .venv /outro/lugar/  # caminhos internos quebram
# Solução: sempre recriar o ambiente no novo local

# Armadilha 4: usar sudo com pip dentro do ambiente
sudo pip install requests  # instala fora do ambiente!
# Solução: nunca use sudo com pip em ambientes virtuais
```

## Alternativas modernas

**Poetry** cria e gerencia ambientes virtuais automaticamente ao executar `poetry install`. Não é necessário criar o ambiente manualmente. O `pyproject.toml` declara dependências com suporte a grupos (prod, dev, test).

**pipenv** foi uma tentativa de unificar pip e virtualenv, mas caiu em desuso frente ao Poetry e ao uv.

**uv** (pela Astral) é a alternativa mais moderna: escrito em [Rust](https://rustlang.com.br/), cria ambientes virtuais em milissegundos e é substancialmente mais rápido que todas as outras opções:

```bash
# uv — criação de ambiente ultrarrápida
uv venv                        # cria .venv
source .venv/bin/activate
uv pip install -r requirements.txt  # instalação também muito mais rápida
```

## Termos Relacionados

- [pip](/glossario/pip/) - Gerenciador de pacotes usado dentro do virtualenv
- [Python](/glossario/python/) - A linguagem de programação
- [Pacote](/glossario/pacote/) - Estrutura de distribuição de código