Primeiros Passos com Matplotlib

Esta página cobre tudo o que você precisa para começar a usar o Matplotlib: como instalá-lo, como importá-lo, como a biblioteca está estruturada e como criar e personalizar seu primeiro gráfico. Ao final, você terá um script funcional que produz um gráfico de linha totalmente rotulado.

Instalando o Matplotlib

O Matplotlib não faz parte da biblioteca padrão do Python, então você deve instalá-lo antes de importá-lo. Use o pip, o gerenciador de pacotes do Python:

pip install matplotlib

Se você estiver trabalhando dentro de um ambiente virtual (recomendado), ative-o primeiro e então execute o comando acima. Para confirmar que a instalação foi bem-sucedida e verificar a versão:

python -m pip show matplotlib

Você deverá ver uma saída como:

Name: matplotlib
Version: 3.9.x
...

O Matplotlib requer Python 3.9 ou mais recente a partir da série de lançamentos 3.9.

Importando o Matplotlib

O Matplotlib está organizado em vários subpacotes. Para uso diário de plotagem, você só precisa do módulo pyplot, que é convencionalmente importado com o apelido plt:

import matplotlib.pyplot as plt

O apelido plt é a convenção universal na comunidade Python. Usá-lo torna seu código consistente com tutoriais, documentação e código que você encontra na web.

Se você também precisar de arrays numéricos (comum ao gerar dados para plotar), importe o NumPy ao mesmo tempo:

import matplotlib.pyplot as plt
import numpy as np

Como o Matplotlib É Estruturado

Entender a estrutura em duas camadas do Matplotlib evita muita confusão:

• Figure — o contêiner de nível superior. Pense nele como a tela ou a janela. Uma Figure pode conter um ou mais Axes.
• Axes — uma única área de plotagem com seu próprio eixo x, eixo y, título e dados. A palavra "Axes" não significa apenas as linhas dos eixos; é toda a região do gráfico.

O Matplotlib expõe duas interfaces para trabalhar com esses objetos:

A interface pyplot gerencia a Figure e os Axes atuais para você. A interface OO fornece manipuladores explícitos para que você possa controlar cada objeto com precisão. Ambas produzem saída idêntica; a diferença está na organização do código.

Criando Seu Primeiro Gráfico

A função plt.plot() desenha uma linha através de uma sequência de pares (x, y). Passe duas listas de comprimento igual — uma para os valores de x e outra para os valores de y:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.show()

plt.show() envia a figura para a tela. Em um script de terminal, a execução é pausada até que você feche a janela do gráfico. Em um notebook Jupyter, o gráfico aparece inline e plt.show() é opcional.

Adicionando Rótulos e um Título

Um gráfico sem rótulos é difícil de interpretar. Adicione rótulos nos eixos e um título com três chamadas de uma linha:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.show()

• plt.xlabel() — rótulo para o eixo horizontal.
• plt.ylabel() — rótulo para o eixo vertical.
• plt.title() — título exibido acima do gráfico.

Personalizando a Cor e o Estilo da Linha

Passe argumentos de palavra-chave para plt.plot() para alterar a aparência da linha:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y, color='steelblue', linewidth=2, linestyle='--')
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.show()

Opções comuns:

Você também pode usar uma string de formato abreviada como terceiro argumento posicional. 'r--' significa vermelho tracejado, 'bs' significa quadrados azuis, 'g^' significa triângulos verdes:

plt.plot(x, y, 'r--')

Definindo Limites dos Eixos

Por padrão, o Matplotlib escolhe limites de eixo que se ajustam aos dados. Você pode substituí-los:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y)
plt.xlim(0, 5)
plt.ylim(0, 20)
plt.show()

plt.xlim(min, max) e plt.ylim(min, max) definem o intervalo visível de cada eixo. Isso é útil quando você deseja destacar uma região específica ou manter os eixos consistentes entre vários gráficos.

Plotando Múltiplas Linhas

Chame plt.plot() mais de uma vez antes de plt.show() para sobrepor várias linhas nos mesmos Axes. Adicione um argumento label a cada chamada e então chame plt.legend() para exibir a legenda:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y_sq = [1, 4, 9, 16, 25]
y_cb = [1, 8, 27, 64, 125]

plt.plot(x, y_sq, color='steelblue', label='x²')
plt.plot(x, y_cb, color='tomato', label='x³')
plt.xlabel('x')
plt.ylabel('y')
plt.title('Comparing Growth')
plt.legend()
plt.show()

plt.legend() lê a string label de cada chamada a plot() e constrói a legenda automaticamente. Coloque-o antes de plt.show().

A Interface Orientada a Objetos

Para qualquer coisa além de um único gráfico simples, a interface OO é mais clara e fácil de manter. Crie uma Figure e um ou mais Axes com plt.subplots(), e então chame métodos diretamente no objeto ax:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y_sq = [1, 4, 9, 16, 25]
y_cb = [1, 8, 27, 64, 125]

fig, ax = plt.subplots()

ax.plot(x, y_sq, color='steelblue', label='x²')
ax.plot(x, y_cb, color='tomato', label='x³')
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Comparing Growth')
ax.legend()
ax.grid(True)

plt.show()

Os nomes dos métodos OO espelham as funções do pyplot com o prefixo set_: plt.xlabel() torna-se ax.set_xlabel(), plt.title() torna-se ax.set_title(), e assim por diante. O manipulador explícito ax torna inequívoco qual gráfico você está modificando — essencial quando uma Figure contém vários subgráficos.

Salvando um Gráfico em um Arquivo

Chame plt.savefig() em vez de (ou além de) plt.show() para gravar a figura no disco:

import matplotlib.pyplot as plt

x = [1, 2, 3, 4]
y = [1, 4, 9, 16]

plt.plot(x, y, color='steelblue', linewidth=2)
plt.xlabel('x')
plt.ylabel('y = x²')
plt.title('Square Numbers')
plt.savefig('square_numbers.png', dpi=150, bbox_inches='tight')

O Matplotlib infere o formato do arquivo pela extensão. Formatos comuns: .png, .pdf, .svg, .jpg. O argumento dpi controla a resolução (150–300 dpi é típico para relatórios). bbox_inches='tight' elimina o espaço em branco das bordas.

Problemas Comuns

Chame plt.show() apenas uma vez. Chamá-lo várias vezes em um script pode produzir figuras em branco porque o Matplotlib limpa a figura atual após exibi-la.

A ordem importa com pyplot. As chamadas de personalização (plt.xlabel(), plt.title(), etc.) devem vir antes de plt.show().

Reutilizando uma figura. Se você constrói um gráfico em um loop e se esquece de limpá-lo, os dados de iterações anteriores se acumulam. Chame plt.clf() (limpar figura) ou plt.close() entre as iterações, ou crie um novo fig, ax = plt.subplots() a cada vez.

Backends não interativos. Em servidores sem display (CI, contêineres Docker), plt.show() pode gerar um erro. Defina o backend antes de importar pyplot:

import matplotlib
matplotlib.use('Agg')  # non-interactive PNG backend
import matplotlib.pyplot as plt

Próximos Passos

Agora que você consegue produzir um gráfico básico, explore os capítulos dedicados:

• Matplotlib Pyplot — mergulho profundo nas funções pyplot e tipos de gráficos
• Matplotlib Line Plots — estilização de linhas, marcadores e fill-between
• Matplotlib Labels — rótulos de eixos, títulos, anotações
• Matplotlib Markers — marcadores de pontos de dados e seus estilos
• Matplotlib Grid — adicionando e configurando linhas de grade
• Matplotlib Subplots — organizando múltiplos gráficos em uma figura
• Matplotlib Bar Charts — gráficos de barras verticais e horizontais
• Matplotlib Scatter Plots — gráficos de dispersão de duas variáveis
• Matplotlib Histograms — distribuições de frequência
• Matplotlib Pie Charts — dados proporcionais