Primeros pasos con Matplotlib

Esta página cubre todo lo que necesitas para empezar a usar Matplotlib: cómo instalarlo, cómo importarlo, cómo está estructurada la biblioteca y cómo crear y personalizar tu primer gráfico. Al finalizar tendrás un script funcional que produce un gráfico de líneas completamente etiquetado.

Instalación de Matplotlib

Matplotlib no forma parte de la biblioteca estándar de Python, por lo que debes instalarlo antes de poder importarlo. Usa pip, el gestor de paquetes de Python:

pip install matplotlib

Si trabajas dentro de un entorno virtual (recomendado), actívalo primero y luego ejecuta el comando anterior. Para confirmar que la instalación se realizó correctamente y comprobar la versión:

python -m pip show matplotlib

Deberías ver una salida similar a:

Name: matplotlib
Version: 3.9.x
...

Matplotlib requiere Python 3.9 o superior a partir de la serie de versiones 3.9.

Importación de Matplotlib

Matplotlib está organizado en varios subpaquetes. Para el trabajo de graficación cotidiano solo necesitas el módulo pyplot, que se importa convencionalmente con el alias plt:

import matplotlib.pyplot as plt

El alias plt es la convención universal en la comunidad Python. Usarlo hace que tu código sea coherente con tutoriales, documentación y código que encuentres en la web.

Si también necesitas arrays numéricos (algo habitual al generar datos para graficar), importa NumPy al mismo tiempo:

import matplotlib.pyplot as plt
import numpy as np

Estructura de Matplotlib

Entender la estructura de dos capas de Matplotlib evita mucha confusión:

• Figure — el contenedor de nivel superior. Piensa en él como el lienzo o la ventana. Una Figure puede contener uno o más Axes.
• Axes — un área de gráfico individual con su propio eje x, eje y, título y datos. La palabra "Axes" no significa solo las líneas de los ejes; es toda la región del gráfico.

Matplotlib expone dos interfaces para trabajar con estos objetos:

La interfaz pyplot gestiona por ti la Figure y los Axes actuales. La interfaz OO te da referencias explícitas para que puedas controlar cada objeto con precisión. Ambas producen resultados idénticos; la diferencia está en la organización del código.

Creación de tu primer gráfico

La función plt.plot() traza una línea a través de una secuencia de pares (x, y). Pasa dos listas de igual longitud: una para los valores x y otra para los valores y:

import matplotlib.pyplot as plt

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

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

plt.show() envía la figura a la pantalla. En un script de terminal, la ejecución se pausa hasta que cierras la ventana del gráfico. En un notebook de Jupyter, el gráfico aparece en línea y plt.show() es opcional.

Añadir etiquetas y un título

Un gráfico sin etiquetas es difícil de interpretar. Añade etiquetas a los ejes y un título con tres llamadas de una sola línea:

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() — etiqueta para el eje horizontal.
• plt.ylabel() — etiqueta para el eje vertical.
• plt.title() — título que se muestra encima del gráfico.

Personalización del color y estilo de línea

Pasa argumentos de palabra clave a plt.plot() para cambiar la apariencia de la línea:

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()

Opciones habituales:

También puedes usar una cadena de formato abreviada como tercer argumento posicional. 'r--' significa rojo discontinuo, 'bs' significa cuadrados azules, 'g^' significa triángulos verdes:

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

Establecer límites de los ejes

Por defecto, Matplotlib elige los límites de los ejes para ajustar los datos. Puedes anularlos:

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) y plt.ylim(min, max) establecen el rango visible de cada eje. Esto es útil cuando quieres resaltar una región específica o mantener los ejes coherentes entre varios gráficos.

Graficar múltiples líneas

Llama a plt.plot() más de una vez antes de plt.show() para superponer varias líneas en los mismos Axes. Añade un argumento label a cada llamada y luego llama a plt.legend() para mostrar la leyenda:

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() lee la cadena label de cada llamada a plot() y construye la leyenda automáticamente. Colócala antes de plt.show().

La interfaz orientada a objetos

Para cualquier cosa más allá de un gráfico simple, la interfaz OO es más clara y fácil de mantener. Crea una Figure y uno o más Axes con plt.subplots(), luego llama a los métodos directamente sobre el 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()

Los nombres de los métodos OO reflejan las funciones de pyplot con el prefijo set_: plt.xlabel() se convierte en ax.set_xlabel(), plt.title() se convierte en ax.set_title(), y así sucesivamente. La referencia explícita ax deja claro qué gráfico estás modificando, algo esencial cuando una Figure contiene varios subgráficos.

Guardar un gráfico en un archivo

Llama a plt.savefig() en lugar de (o además de) plt.show() para escribir la figura en el 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')

Matplotlib infiere el formato del archivo a partir de la extensión. Formatos habituales: .png, .pdf, .svg, .jpg. El argumento dpi controla la resolución (150–300 dpi es típico para informes). bbox_inches='tight' recorta el espacio en blanco de los bordes.

Errores comunes

Llama a plt.show() solo una vez. Llamarlo varias veces en un script puede producir figuras en blanco porque Matplotlib borra la figura actual después de mostrarla.

El orden importa con pyplot. Las llamadas de personalización (plt.xlabel(), plt.title(), etc.) deben realizarse antes de plt.show().

Reutilizar una figura. Si construyes un gráfico en un bucle y olvidas limpiarlo, los datos de iteraciones anteriores se acumulan. Llama a plt.clf() (limpiar figura) o plt.close() entre iteraciones, o crea un nuevo fig, ax = plt.subplots() cada vez.

Backends no interactivos. En servidores sin pantalla (CI, contenedores Docker), plt.show() puede lanzar un error. Establece el backend antes de importar pyplot:

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

Próximos pasos

Ahora que puedes producir un gráfico básico, explora los capítulos dedicados:

• Matplotlib Pyplot — análisis profundo de las funciones de pyplot y tipos de gráficos
• Matplotlib Line Plots — estilizado de líneas, marcadores y relleno entre curvas
• Matplotlib Labels — etiquetas de ejes, títulos, anotaciones
• Matplotlib Markers — marcadores de puntos de datos y sus estilos
• Matplotlib Grid — añadir y configurar líneas de cuadrícula
• Matplotlib Subplots — organizar múltiples gráficos en una figura
• Matplotlib Bar Charts — gráficos de barras verticales y horizontales
• Matplotlib Scatter Plots — gráficos de dispersión de dos variables
• Matplotlib Histograms — distribuciones de frecuencia
• Matplotlib Pie Charts — datos proporcionales