Matplotlib imshow(): Display Images and Arrays in Python

matplotlib.pyplot.imshow() displays image data or a 2D NumPy array on Matplotlib axes. It is the standard Matplotlib tool for showing photos, masks, heatmaps, grayscale arrays, and pixel-level debugging output.

The important idea is that imshow() maps array values to pixels. A 2D array is shown as a colored grid using a colormap. A 3D array with shape like (height, width, 3) or (height, width, 4) is displayed as an RGB or RGBA image.

Use imshow() when the data already has image-like structure: rows, columns, and optional color channels. It is not the right tool for ordinary x/y line data, but it is excellent for inspecting image preprocessing steps, segmentation masks, model inputs, small matrices, and raster outputs created by other libraries.

For publication or documentation, decide early whether the axes should show coordinates or whether the image should stand alone. That decision affects axis("off"), figure size, labels, and export settings.

Display an image file with imshow()

Use plt.imread() to load a supported image file, then pass the result to ax.imshow(). Hide the axes when the tick marks do not add useful information.

import matplotlib.pyplot as plt

image = plt.imread("sample.png")

fig, ax = plt.subplots(figsize=(6, 4))
ax.imshow(image)
ax.axis("off")
ax.set_title("Image shown with imshow")

plt.show()

The official pyplot.imread documentation explains image loading. Python Pool’s Matplotlib imread guide covers image-file reading in more detail.

Display a NumPy array

For a 2D numeric array, imshow() applies a colormap. Add a colorbar when the numeric scale matters.

import matplotlib.pyplot as plt
import numpy as np

data = np.array([
    [0.1, 0.4, 0.7],
    [0.3, 0.8, 0.5],
    [0.9, 0.6, 0.2],
])

fig, ax = plt.subplots(figsize=(5, 4))
im = ax.imshow(data, cmap="viridis")
fig.colorbar(im, ax=ax, label="value")
ax.set_title("Array displayed with imshow")

plt.show()

For matrix-style visualizations, see the Python Pool guide to Matplotlib heatmaps. The official pyplot.imshow documentation lists all supported parameters.

Use grayscale and colormaps

A grayscale image or a 2D intensity array should usually be plotted with cmap="gray". For scientific arrays, choose a colormap that matches the data meaning.

gray = np.array([
    [0, 40, 80, 120],
    [40, 80, 120, 160],
    [80, 120, 160, 200],
    [120, 160, 200, 255],
], dtype="uint8")

fig, ax = plt.subplots(figsize=(4, 4))
ax.imshow(gray, cmap="gray", vmin=0, vmax=255)
ax.axis("off")
plt.show()

Use vmin and vmax to keep the color scale consistent across multiple images. The official Matplotlib colormap guide and Python Pool’s Matplotlib cmap guide can help you choose the right palette. For custom palettes, see Matplotlib custom colormaps.

Control interpolation

interpolation controls how Matplotlib draws pixels when the image is scaled on screen. Use nearest when individual pixels should stay sharp, such as masks or small arrays. Use smooth interpolation for continuous-looking photos or fields.

fig, axes = plt.subplots(1, 2, figsize=(8, 4))

axes[0].imshow(data, cmap="viridis", interpolation="nearest")
axes[0].set_title("nearest")

axes[1].imshow(data, cmap="viridis", interpolation="bilinear")
axes[1].set_title("bilinear")

for ax in axes:
    ax.axis("off")

plt.show()

The Matplotlib interpolation methods example shows how different interpolation choices affect image rendering. If your plot is meant to explain exact pixel classes, avoid smoothing because it can imply values that are not present in the source array.

Set aspect, origin, and extent

By default, images use an equal aspect ratio so square pixels look square. Change aspect only when the plot needs to fit a specific layout or when the x/y units have a known relationship.

fig, ax = plt.subplots(figsize=(6, 4))
ax.imshow(data, cmap="magma", origin="lower", extent=(0, 10, 0, 5), aspect="auto")
ax.set_xlabel("x distance")
ax.set_ylabel("y distance")
plt.show()

The Axes.imshow documentation covers origin, extent, and aspect. For layout decisions, see Python Pool’s Matplotlib aspect ratio and Matplotlib figsize guides.

Convert image objects to arrays

If an image comes from Pillow or another library, convert it to a NumPy array before using imshow(). Matplotlib can then display the pixel data directly.

from PIL import Image
import matplotlib.pyplot as plt
import numpy as np

picture = Image.open("sample.jpg")
array = np.asarray(picture)

fig, ax = plt.subplots(figsize=(6, 4))
ax.imshow(array)
ax.axis("off")
plt.show()

The NumPy asarray documentation explains the conversion. Python Pool also has guides for PIL image to NumPy array and rotating images in Python.

Common imshow mistakes

Wrong data shape. Use a 2D array for scalar data, or a 3D array with RGB/RGBA channels for color images. Check array.shape before plotting when output looks strange.

Unexpected colors. Set cmap, vmin, and vmax explicitly when the colors need to mean the same thing across plots.

Blurry masks or pixel art. Use interpolation="nearest" when each pixel should remain visible.

Distorted output. If the image looks stretched, check aspect, figure size, and the dimensions of the source array. Do not use aspect="auto" unless stretching is acceptable.

Image dtype errors. Matplotlib expects numeric image data. If you see dtype conversion errors, check the array values and see Python Pool’s guide to image data dtype errors.

Conclusion

Use imshow() when you need to display image-like data in Matplotlib. Load image files with imread(), pass arrays directly, choose an appropriate colormap, control interpolation for pixel clarity, and adjust aspect settings when the image is part of a larger plot.