Folha de Dicas do Python venv

alguns comandos úteis de venv

Conteúdo da página

Venv é uma ferramenta de linha de comando para gerenciamento de ambientes virtuais. Uma muito mais simples, comparada com a Anaconda. Aqui estão alguns comandos úteis do venv.

Um python está tentando abrir uma caixa de madeira.

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

Folha de Dicas 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 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 mostrar o nome do ambiente.

Desativar o Ambiente Virtual

  • Em todos os sistemas: 
    deactivate
    Isso o 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 o ambiente virtual esteja ativado antes de executar esses comandos.

Remover um Ambiente Virtual

deactivate
rm -rf <caminho do ambiente>

Erros Comuns ao Gerenciar Ambientes Virtuais do Python

Esquecer de Ativar o Ambiente Virtual

  • Um erro comum é executar comandos sem ativar o ambiente virtual desejado, resultando na instalação de pacotes no ambiente global ou no ambiente errado. Isso pode causar conflitos de dependências e comportamento imprevisível.

Não Fixar Versões de Pacotes

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

Misturar Ambientes Globais e Virtuais

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

Incluir Ambientes Virtuais no Controle de Versão

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

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

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

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) dificulta a onboarding de novos contribuidores e a reprodução de ambientes.

Não Limpar Ambientes Antigos com Regularidade

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

Ignorar Limites 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 do projeto e evite interferir em pacotes gerenciados pelo sistema.

Tabela de Resumo

Erro Comum 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ências/versões
Incluir diretórios de venv no controle de versão Repositórios inchados e bagunçados
Não separar dependências de desenvolvimento e produção Implantações inchadas/inseguras
Falta de documentação/automação Dificuldade no onboarding, configurações inconsistentes
Não limpar ambientes antigos Perda de espaço em disco, confusão
Modificar o Python do sistema ou pacotes Instabilidade do sistema, ferramentas quebradas

Seguir práticas recomendadas, como sempre ativar seu venv, fixar dependências, separar ambientes e manter documentação clara, pode ajudá-lo a evitar esses erros comuns.

Principais Diferenças Entre Conda e Ambientes Virtuais para Reprodutibilidade

Funcionalidade Ambientes Conda Ambientes Virtuais do Python (venv/virtualenv)
Escopo de Gerenciamento Gerencia pacotes do Python e dependências não-Python (ex: bibliotecas do sistema, compiladores) Gerencia apenas pacotes do Python via pip
Controle de Versão do Python Pode especificar e instalar qualquer versão do Python por ambiente Usa a versão do Python instalada no sistema
Consistência em Diferentes Plataformas Mais consistente entre diferentes OS (Windows, macOS, Linux) devido ao gerenciamento de todas as dependências Depende das 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 do Python
Reprodutibilidade Maior para projetos complexos, científicos ou com linguagens mistas; pode exportar o ambiente completo (conda env export) Boa para projetos puramente 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
Exportação/Importação de Ambiente conda env export / conda env create para reprodutibilidade total pip freeze > requirements.txt / pip install -r requirements.txt (apenas pacotes do Python)
Desempenho Mais rápido e confiável para grandes pacotes científicos (ex: numpy, pandas) Pode exigir compilação a partir do código-fonte, especialmente no Windows
Complexidade Slightly higher setup and management overhead Leve, simples para projetos básicos em Python

Resumo dos Pontos Principais

  • Ambientes Conda são ideais para reprodutibilidade em projetos que exigem tanto pacotes do Python quanto dependências 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 do Python (venv/virtualenv) são leves e excelentes para isolar dependências do Python em projetos puramente em Python. No entanto, eles não gerenciam dependências do sistema ou não-Python, então a reprodutibilidade pode ser comprometida se o projeto depender de bibliotecas externas ou configurações específicas do sistema.

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

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