O que realmente é borboletas na chuva
É um pacote Python para visualização de dados meteorológicos com foco em dados de precipitação e padrões climáticos regionais. A biblioteca foi criada inicialmente como um projeto de código aberto no GitHub, e o nome vem de uma piada interna do desenvolvedor original sobre borboletas aparecendo depois das chuvas no cerrado brasileiro. Não tem relação direta com entomologia ou meteorologia avançada. É uma ferramenta de visualização, não de simulação climática. As pessoas costumam confundir isso na primeira vez que tentam usar.
Como instalar borboletas na chuva
A instalação é direto. Abra o terminal e rode: pip install borboletas-na-chuva
Depois de instalar, você precisa ter o Python 3.9 ou superior. Eu já perdi uns vinte minutos testando com a versão 3.8 porque o pacote simplesmente não instalava e o erro no pip era tão vago que parecia bug do próprio gerenciador. Atualize antes de qualquer coisa. Se estiver no Windows, certifique-se de que o caminho do pip está no PATH. Se não estiver, rode pelo prompt de comando como administrador: python -m pip install borboletas-na-chuva.
Primeiros passos com a biblioteca
A estrutura básica é mais simples do que a documentação sugere. O fluxo padrão envolve carregar dados, filtrar por região e gerar um gráfico de séries temporais. O problema é que a função principal de carga, load_precip_data(), espera arquivos no formato CSV com colunas específicas. Se as colunas não estiverem nomeadas exatamente como date, station_id, rainfall_mm e region, o pacote falha silenciosamente — ele não lança exceção, apenas retorna um DataFrame vazio. Perdi uma tarde inteira com isso em 2024, porque o pacote não reportava erro algum. A solução foi adicionar uma verificação manual dos cabeçalhos antes de passar os dados para a função.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Exemplo prático
Aqui vai um exemplo funcional que eu uso no meu dia a dia:
from borboletas_na_chuva import load_precip_data, plot_rainfall_pattern
df = load_precip_data("dados_meteorologicos.csv")
if df.empty:
print("Verifique os nomes das colunas do CSV")
else:
plot_rainfall_pattern(df, region="Sudeste", period="mensal")
Isso gera um gráfico de linhas com as médias mensais de precipitação para a região Sudeste, com intervalos de confiança em tom mais claro ao redor da linha principal. O gráfico leva cerca de 2 a 3 segundos para ser renderizado em máquinas comuns com datasets de até 50 mil linhas.
Limitações que ninguém mencion
O pacote não suporta dados de estações fora do Brasil. Tentei usar com dados da Argentina e ele simplesmente não carregava, sem nenhum aviso. A documentação diz que é "extensível para outros países", mas essa funcionalidade nunca foi implementada de fato. Se você trabalha com dados sul-americanos, use outra ferramenta para o resto do continente. Outro ponto: a biblioteca depende do matplotlib e do pandas. Se você tiver conflitos de versão com outras bibliotecas no seu ambiente, especialmente o numpy, pode encontrar erros de compatibilidade difíceis de diagnosticar. Em 2025, tive um projeto inteiro quebrado porque atualizei o numpy e o borboletas na chuva parou de funcionar. Reverter para a versão anterior do numpy resolveu, mas não havia forma automática de fazer isso.
O pacote também não tem suporte a Jupyter notebooks de forma nativa. O comando de plotagem funciona, mas a saída não aparece inline automaticamente. Você precisa chamar plt.show() no final, mesmo que a documentação não deixe isso claro.
Alternativas quando borboletas na chuva não funciona
Se você precisa de visualizações meteorológicas mais robustas, o meteostat é uma alternativa sólida. Ele cobre toda a América Latina, tem API própria, funciona bem com Jupyter e não tem as limitações regionais do borboletas na chuva. A curva de aprendizado é ligeiramente maior, mas compensa em projetos maiores. Para análises mais pontuais dentro do Brasil, o borboletas na chuva ainda é útil. Mas saiba das limitações antes de depender dele em produção.
