Python docx offers different ways to display an image in a document. We can show single image or multiple inline images. We can also add image to a table in document. We can also work with image captions and can handle other image properties like height or width.
First we create a empty document and add a image from path to document using add_picture method
# Create/Open a document
from docx import Document
doc = Document()

# add image and save doc
doc.add_heading("Image", 0)

Here is the output for document image.

My alt text

Python docx also allows to specify image width, height, alignment and different other options. For example, we can specify width and height of a image in document in add_picture method.

from docx.shared import Inches

# add image with height and width in Inches
doc.add_picture("images/emma-dau.jpg", width=Inches(5), height=Inches(3))

We can get paragraph containing image and can apply operations like alignment.

from docx.enum.text import WD_ALIGN_PARAGRAPH
# add picture
doc.add_picture("images/emma-dau.jpg", width=Inches(5), height=Inches(3))
# Get image paragraph and align
last_paragraph = doc.paragraphs[-1] 
last_paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER


We can also show images in Grid form using python-docx and some processing. For this, we first need to define height and width of each image so we can add to document. To create a grid, we add a paragraph to document and add images to it with specified width and height. For spacing between each image in a row, we simply add a string with space.

# grid code here
from docx import Document
from docx.shared import Inches
import os
# create document
document = Document()
# add heading
document.add_heading('Grid Images', 0)
# add paragraph and get run
p = document.add_paragraph()
r = p.add_run()
# iterate over each image in directory
for image_name in os.listdir("images"):
    # add image so it creates a row with 4 images
    r.add_picture(f"images/{image_name}", width=Inches(1.46), height=Inches(1.45))
    r.add_text(" ") # add space for image seperation
# save document'demo.docx')

My alt text

Image width can be changed to increase or decrease images in a row.

Images in Tables

Working with tables makes it easier to show data in a good way. So, we can also use tables and add images to table cells and can also add other data like text, captions etc.

For adding padding to cells in table, view this function code on stackoverflow.

For this tables example, we iterate on each image in directory and add image and image name to table rows.

from docx.shared import Inches, Cm
import os
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document() # create doc
doc.add_heading('Images in Table', 0) # add heading

# create table with two rows and columns (Per row images are 3)
table = doc.add_table(rows=0, cols=3, style="Table Grid")
image_dir = "images"
images = os.listdir(image_dir )

for i in range(4): # show 4 rows of image (4x3 = 12 images)
    image_row = table.add_row() # add row to table for images
    cap_row = table.add_row() # add row to table for image name
    for j in range(3): # Iterate and get 3 images for row
        image_name = images.pop()

        # add image to table
        set_cell_margins(image_row.cells[j], top=100, start=100, bottom=100, end=50)
        # add image to cell and align center
        paragraph = image_row.cells[j].paragraphs[0] 
        paragraph.add_run().add_picture(f"{image_dir }/{image_name}", width=Inches(1.8), height=Inches(1.6))
        paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER

        # add caption to table
        cap_row.cells[j].text = image_name
        cap_row.cells[j].paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# save to file"images-table.docx")

 This way we can create a very good looking Grid using table to show images and other text data.

My alt text

This way, we can handle images and add different views to python docx using single or multiple images and make a good presentation of document.

For more info on working with images using python docx, view official documentation of python-docx.