Add Images to docx Using Python-docx

Python makes document automation easy. The python-docx library helps you create Word documents. You can add text, tables, and images. This guide shows how to insert images.

Adding images to Word documents is common. Reports, invoices, and presentations need images. Manual insertion takes time. Automation saves effort and ensures consistency.

Installing python-docx

First, install the library. Use pip for installation. Run this command in your terminal.

pip install python-docx

If you need help with installation, check our Install python-docx for Word Documents in Python guide. It provides detailed instructions.

Basic Image Insertion

Start by importing the library. Create a document object. Use the add_picture() method to insert images. This method is simple and powerful.

from docx import Document

# Create a new document
doc = Document()

# Add a heading
doc.add_heading('Document with Image', 0)

# Insert an image
doc.add_picture('sample.jpg')

# Save the document
doc.save('document_with_image.docx')

The code creates a new Word document. It adds a heading and inserts an image. The image file must be in the same directory. Otherwise, provide the full path.

Image Positioning and Alignment

Control where images appear. Use paragraph alignment. Images are added to paragraphs. You can align them left, center, or right.

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

# Add a centered image
paragraph = doc.add_paragraph()
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
run = paragraph.add_run()
run.add_picture('sample.jpg')

doc.save('aligned_image.docx')

This code centers the image. The WD_ALIGN_PARAGRAPH enum provides alignment options. CENTER, LEFT, and RIGHT are available.

Image Size Control

Resize images in your document. Specify width and height. Use inches or centimeters for measurements. Maintain aspect ratio for best results.

from docx import Document
from docx.shared import Inches

doc = Document()

# Add image with specific size
doc.add_picture('sample.jpg', width=Inches(4), height=Inches(3))

doc.save('sized_image.docx')

The image will be 4 inches wide and 3 inches high. The Inches class converts measurements. You can also use Cm for centimeters.

Adding Images to Existing Documents

You can modify existing documents. Open them and add images. The process is similar to creating new documents.

from docx import Document

# Open existing document
doc = Document('existing_document.docx')

# Add image to the end
doc.add_picture('new_image.png')

# Save the modified document
doc.save('updated_document.docx')

This code opens an existing file. It adds an image at the end. Save with a new name to preserve the original.

Image Wrapping and Text Flow

Control how text flows around images. Python-docx supports inline images by default. For advanced wrapping, you need deeper manipulation.

Inline images appear within text lines. They don't have text wrapping. For most use cases, this is sufficient.

Multiple Images in Document

Add several images to one document. Loop through image files. Insert each one with custom formatting.

from docx import Document
from docx.shared import Inches

doc = Document()
image_files = ['image1.jpg', 'image2.png', 'image3.gif']

for image_file in image_files:
    doc.add_paragraph(f"Image: {image_file}")
    doc.add_picture(image_file, width=Inches(3))
    doc.add_paragraph()  # Add empty paragraph for spacing

doc.save('multiple_images.docx')

This code adds multiple images. Each image has a caption and consistent width. Empty paragraphs create spacing between images.

Error Handling

Handle missing image files gracefully. Use try-except blocks. Prevent your script from crashing.

from docx import Document
import os

doc = Document()

image_path = 'missing_image.jpg'

if os.path.exists(image_path):
    doc.add_picture(image_path)
else:
    doc.add_paragraph('Image not found: ' + image_path)

doc.save('safe_document.docx')

This code checks if the image exists. If not, it adds a text message. This prevents FileNotFound errors.

Supported Image Formats

Python-docx supports common image formats. JPEG, PNG, and BMP work well. GIF images are also supported.

For best results, use JPEG for photos. Use PNG for images with transparency. Check your image format before insertion.

Advanced Image Placement

For complex document layouts, consider our Python-docx Tutorial: Create Word Documents. It covers advanced formatting techniques.

You can also learn about Python-docx Paragraph Formatting Guide for better text management around images.

Conclusion

Adding images to Word documents with Python is straightforward. The python-docx library provides simple methods. You can control size, position, and alignment.

Automate your document creation process. Save time and ensure consistency. Experiment with different image configurations for your needs.

Remember to handle errors and check file paths. Your documents will look professional with properly formatted images.