Como salvar gráficos como arquivos de imagem sem exibi-los no Matplotlib

Para salvar um gráfico completo do Matplotlib como imagem sem abrir uma janela gráfica, omita show(), salve a figura específica com savefig() e feche-a somente depois de gravar o arquivo. Em ambientes realmente sem interface gráfica, selecione o backend não interativo Agg antes de importar pyplot.

Salvar um gráfico do Matplotlib sem exibi-lo

Para salvar uma figura completa do Matplotlib sem abrir uma janela gráfica, não chame show(): use savefig() na figura específica e só chame close() depois que o arquivo tiver sido gravado. Em um servidor, uma tarefa de CI, um contêiner ou outro ambiente que exija explicitamente um backend headless, selecione o backend estático Agg antes de importar matplotlib.pyplot.

A ordem essencial é, portanto, selecionar o backend, criar a figura, salvá-la e depois fechá-la. Manter a referência ao objeto Figure elimina ambiguidades e evita depender de qual figura o pyplot considera ativa naquele momento.

Selecionar Agg explicitamente é mais útil quando o script precisa funcionar de forma consistente em uma máquina sem servidor de exibição. Isso não é obrigatório apenas porque o script salva um arquivo: o próprio Matplotlib pode escolher automaticamente um backend não interativo adequado. Se não for possível editar o comando, também se pode definir o backend com a variável de ambiente MPLBACKEND=Agg. Evite combinar vários métodos de seleção sem necessidade, pois o Matplotlib segue uma ordem de precedência e a última configuração aplicável prevalece.

Salvar uma figura com o backend headless Agg

O exemplo testado a seguir salva um gráfico de onda senoidal como sine-wave.png sem chamar show(). O Agg é um backend não interativo que gera imagens rasterizadas, portanto não precisa de uma janela visível.

from pathlib import Path

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt
import numpy as np

output = Path("sine-wave.png")
x = np.linspace(0, 2 * np.pi, 200)

fig, ax = plt.subplots(figsize=(6, 4))
ax.plot(x, np.sin(x), color="#2166ac", linewidth=2)
ax.set(title="Sine wave", xlabel="x", ylabel="sin(x)")
ax.grid(alpha=0.25)

fig.savefig(output, dpi=150, bbox_inches="tight")
plt.close(fig)

saved = plt.imread(output)
assert output.is_file() and saved.size > 0
print("backend:", matplotlib.get_backend())
print("saved:", output.name)
print("valid PNG:", True)

A saída verificada é:

backend: Agg
saved: sine-wave.png
valid PNG: True

A imagem é gravada em relação ao diretório de trabalho atual do processo. Um Path absoluto ou construído a partir de um diretório conhecido do projeto é mais seguro quando um agendador ou serviço pode iniciar o script em outro local.

As asserções reabrem o PNG gerado e confirmam que o arquivo existe e contém dados de imagem. Essa verificação detecta uma saída ausente ou ilegível, enquanto a prévia renderizada acima confirma a curva, os rótulos e a grade esperados. Em produção, escolha uma verificação igualmente concreta quando uma exportação vazia ou salva no lugar errado tiver um custo relevante.

Escolher o formato da imagem e as opções de savefig()

O método Figure.savefig() normalmente deduz o formato pela extensão do nome do arquivo. Use PNG para uma imagem rasterizada amplamente compatível, SVG para gráficos vetoriais escaláveis na web e PDF para um documento vetorial. Se o nome não tiver uma extensão apropriada, informe explicitamente o argumento format.

Para arquivos rasterizados, dpi controla a resolução de saída; ele não deixa os traços vetoriais de SVG ou PDF mais nítidos. bbox_inches="tight" remove o espaço excedente ao redor do conteúdo, enquanto transparent=True torna transparentes os fundos da figura e dos eixos, salvo quando suas cores são sobrescritas. Essas opções alteram o arquivo exportado, não determinam se uma janela será aberta. Os formatos disponíveis também podem depender do backend e das bibliotecas opcionais instaladas.

Escolha o formato conforme o destino. PNG é adequado para um gráfico inserido em um documento ou página web; SVG continua nítido quando o navegador redimensiona linhas e texto; PDF é conveniente para impressão. Um dpi alto aumenta as dimensões e o tamanho do arquivo rasterizado, por isso defina-o segundo os requisitos reais de exibição ou impressão.

Entender ioff(), show() e a ordem de salvamento

plt.ioff() desativa o modo interativo do pyplot, mas não é um interruptor headless universal. Em particular, interfaces de notebook podem exibir automaticamente a última figura de uma célula mesmo com o modo interativo desligado. Use Agg quando precisar de um renderizador sem interface gráfica e, em um notebook, suprima o valor final da figura ou feche-a explicitamente depois de salvar.

Por outro lado, savefig() não precisa do modo interativo nem de show(). show() serve para apresentar figuras por um backend interativo; omiti-lo é a escolha normal em um script que apenas exporta arquivos. Desativar a interação e selecionar um backend de arquivo resolvem problemas relacionados, mas diferentes.

Salve antes de chamar close(fig). Fechar primeiro remove do pyplot a referência à figura, de modo que um plt.savefig() posterior pode atingir outra figura ou uma figura recém-criada. De forma semelhante, a documentação de show() alerta que salvar depois de um show() bloqueante pode gerar uma figura vazia; salve primeiro ou mantenha o objeto da figura e chame seu método savefig().

Liberar figuras em loops e salvar na memória

O pyplot mantém referências às figuras criadas por sua interface. Uma tarefa em lote que cria muitos gráficos deve chamar close(fig) depois de cada salvamento bem-sucedido, para que as figuras e sua memória possam ser liberadas. Use um padrão de limpeza try/finally quando etapas posteriores puderem falhar.

Quando outra API precisa dos bytes da imagem e nenhum arquivo em disco é necessário, passe um objeto io.BytesIO a fig.savefig() no lugar de um caminho. Volte o buffer ao início com seek(0) antes de ler ou enviar os dados, e ainda feche a figura depois de salvá-la.

Tratar um diretório de saída inexistente

savefig() cria o arquivo de imagem, mas não cria diretórios-pai ausentes. Este exemplo de limite verificado captura essa falha e fecha a figura em todos os casos:

from pathlib import Path

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt

output = Path("missing") / "plot.png"
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [2, 4, 3])

try:
    fig.savefig(output)
except FileNotFoundError:
    print("Create the parent directory before savefig().")
finally:
    plt.close(fig)

Create the parent directory before savefig().

Em uma exportação real, crie primeiro o diretório com output.parent.mkdir(parents=True, exist_ok=True). Verifique também se o processo tem permissão para gravar nesse local.

Usar imsave() para uma matriz numérica

Use matplotlib.pyplot.imsave() quando a entrada for uma matriz numérica 2D ou RGB(A), e não uma figura desenhada com eixos, rótulos, legendas e outros artistas. Ele mapeia os valores da matriz para pixels da imagem e não substitui Figure.savefig() para um gráfico completo.

from pathlib import Path

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt
import numpy as np

pixels = np.array([[0.0, 0.5, 1.0], [1.0, 0.5, 0.0]])
output = Path("array-image.png")

plt.imsave(output, pixels, cmap="gray", vmin=0, vmax=1)

saved = plt.imread(output)
assert output.is_file() and saved.shape[:2] == pixels.shape
print("saved array:", output.name)
print("pixel grid:", saved.shape[0], "x", saved.shape[1])

saved array: array-image.png
pixel grid: 2 x 3