Guia de Referência Rápida do Python venv

alguns comandos úteis do venv

Conteúdo da página

[Venv é uma ferramenta de linha de comando para gerenciamento de ambientes virtuais](https://www.glukhov.org/pt/post/2025/05/python-venv-cheatsheet/ “Guia de comandos e atalhos do Venv e seus comandos mais úteis.). Uma opção muito mais simples em comparação com o Anaconda. Aqui estão alguns comandos úteis do venv.

Uma python tentando abrir uma caixa de madeira.

Apenas para sua informação, existe, na minha opinião, uma ferramenta muito melhor para gerenciamento de pacotes e ambientes em Python do que o venv: o uv. Dê uma olhada: uv - Novo Gerenciador de Pacotes, Projetos e Ambientes Python

Guia Rápido do Python venv

Criar um Ambiente Virtual

  • Comando padrão (Python 3.3+):

    python -m venv venv

    Isso cria um ambiente virtual chamado venv no seu diretório atual.

  • Com uma versão específica do Python (se instalada):

    python3.10 -m venv venv

    ou usando virtualenv:

    virtualenv -p /usr/local/bin/python3.10 venv

    (Requer o pacote virtualenv).

Ativar o Ambiente Virtual

  • No Windows: 
    .\venv\Scripts\activate
  • No macOS/Linux: 
    source venv/bin/activate
    O prompt do shell agora deve exibir o nome do ambiente.

Desativar o Ambiente Virtual

  • Todas as plataformas: 
    deactivate
    Isso retorna ao Python do sistema.

Instalar Pacotes

  • Com o pip: 
    pip install
    Exemplo: 
    pip install numpy pandas
  • Atualizar o pip (recomendado): 
    python -m pip install --upgrade pip

Congelar e Exportar Requisitos

  • Salvar os pacotes do ambiente atual: 
    pip freeze > requirements.txt
  • Instalar a partir do arquivo de requisitos: 
    pip install -r requirements.txt
    Certifique-se de que seu ambiente virtual esteja ativado antes de executar esses comandos.

Remover um Ambiente Virtual

deactivate
rm -rf <caminho do ambiente>

Armadilhas Comuns ao Gerenciar Ambientes Virtuais Python

Esquecer de Ativar o Ambiente Virtual

  • Um erro frequente é executar comandos sem ativar o ambiente virtual pretendido, levando a instalações de pacotes no ambiente global ou no venv errado. Isso pode causar conflitos de dependências e comportamentos imprevisíveis.

Não Fixar Versões de Pacotes

  • Usar especificadores de versão soltos (como >= em vez de ==) em requirements.txt prejudica a reprodutibilidade. A fixação exata de versões garante que todos que trabalham no projeto usem as mesmas versões de pacotes, evitando problemas inesperados durante a implantação ou colaboração.

Misturar Ambientes Globais e Virtuais

  • Instalar pacotes globalmente por acidente ou misturar ambientes globais e virtuais pode criar conflitos, especialmente se projetos diferentes exigirem versões incompatíveis de pacotes. Sempre certifique-se de estar operando dentro do ambiente correto.

Commitar Ambientes Virtuais no Controle de Versão

  • Incluir o diretório do ambiente virtual (por exemplo, venv/) no controle de versão infla os repositórios e é desnecessário. Sempre adicione diretórios venv ao .gitignore para manter seu repositório limpo.

Negligenciar a Separação de Dependências de Desenvolvimento e Produção

  • Falhar em distinguir entre dependências de desenvolvimento e de produção pode resultar em implantações inchadas ou inseguras. Use arquivos de requisitos separados ou seções de configuração para cada um.

Falta de Documentação e Automação

  • Não documentar os passos de configuração do ambiente ou falhar em automatizar o processo (com scripts ou Makefiles) torna a integração de novos contribuidores e a reprodução de ambientes mais difícil.

Não Limpar Regularmente Ambientes Antigos

  • Com o tempo, ambientes virtuais não utilizados podem se acumular, desperdiçando espaço em disco e causando confusão. Remova regularmente venvs obsoletos para manter um espaço de trabalho organizado.

Ignorar as Fronteiras do Python do Sistema e do Gerenciador de Pacotes

  • Modificar o Python do sistema ou misturar gerenciadores de pacotes do sistema com o pip pode quebrar ferramentas do sistema e introduzir problemas difíceis de diagnosticar. Sempre use venvs para dependências de projetos e evite interferir com pacotes gerenciados pelo sistema.

Tabela de Resumo

Armadilha Impacto
Esquecer de ativar o venv Instala pacotes no ambiente errado
Não fixar versões de pacotes Builds imprevisíveis, bugs difíceis de reproduzir
Misturar ambientes globais e virtuais Conflitos de dependência/versão
Commitar diretórios venv no controle de versão Repositórios inchados e bagunçados
Não separar dependências dev e prod Ambientes de produção inchados/inseguros
Falta de documentação/automação Integração difícil, configurações inconsistentes
Não limpar ambientes antigos Desperdício de espaço em disco, confusão
Modificar Python do sistema ou pacotes Instabilidade do sistema, ferramentas quebradas

Seguir as melhores práticas, como sempre ativar seu venv, fixar dependências, separar ambientes e manter documentação clara, pode ajudar você a evitar essas armadilhas comuns.

Diferenças Chave Entre Conda e Ambientes Virtuais para Reprodutibilidade

Característica Ambientes Conda Ambientes Virtuais Python (venv/virtualenv)
Escopo de Gerenciamento Gerencia pacotes Python e dependências não-Python (ex: bibliotecas do sistema, compiladores) Gerencia apenas pacotes Python via pip
Controle de Versão Python Pode especificar e instalar qualquer versão do Python por ambiente Usa a versão do Python instalada no sistema
Consistência Cross-Plataforma Mais consistente em diferentes SOs (Windows, macOS, Linux) devido ao gerenciamento de todas as dependências Depende de bibliotecas do sistema, que podem variar por OS
Fontes de Pacotes Usa repositórios Conda (binários pré-compilados, pilha científica) Usa PyPI (pip) para pacotes Python
Reprodutibilidade Maior para projetos complexos, científicos ou multilíngues; pode exportar ambiente completo (conda env export) Bom para projetos puros em Python; pode faltar reprodutibilidade se dependências do sistema estiverem envolvidas
Dependências Não-Python Pode instalar e gerenciar (ex: OpenBLAS, libpng) Não pode gerenciar; deve ser instalado separadamente
Exportar/Importar Ambiente conda env export / conda env create para reprodutibilidade total pip freeze > requirements.txt / pip install -r requirements.txt (apenas pacotes Python)
Desempenho Mais rápido e confiável para pacotes científicos grandes (ex: numpy, pandas) Pode exigir compilação a partir do código-fonte, especialmente no Windows
Complexidade Sobre carga de configuração e gerenciamento ligeiramente maior Leve, mais simples para projetos básicos em Python

Resumo dos Pontos Chave

  • Ambientes Conda são ideais para reprodutibilidade em projetos que exigem dependências Python e não-Python, ou quando a replicação exata entre plataformas é crítica. O Conda gerencia toda a pilha, incluindo o próprio Python, bibliotecas e até compiladores, tornando mais fácil compartilhar e reproduzir ambientes complexos, especialmente em contextos de ciência de dados e pesquisa.

  • Ambientes virtuais Python (venv/virtualenv) são leves e excelentes para isolar dependências Python em projetos puros em Python. No entanto, eles não gerenciam dependências de nível do sistema ou não-Python, então a reprodutibilidade pode ser comprometida se seu projeto depender de bibliotecas externas ou configurações de sistema específicas.

  • Exportar e compartilhar ambientes: O Conda permite exportar uma especificação completa de ambiente (conda env export), incluindo todas as dependências e suas versões, que pode ser recriada exatamente em outro lugar. Com ambientes virtuais, pip freeze captura apenas pacotes Python, não dependências do sistema ou a versão do interpretador Python.

  • Conclusão
    Use o Conda para máxima reprodutibilidade em projetos científicos, cross-plataforma ou projetos complexos. Use ambientes virtuais Python para projetos leves e puros em Python onde as dependências do sistema não são uma preocupação.