Insert and Manipulate Images in Excel Using Python

Excel reports often need images: a company logo, a product render, an electronic signature, or a scanned document thumbnail. An image must land in the right cell, at the right size, without crowding the surrounding data. When a batch of reports all need the same logo, or a template must be cleared of old images before new ones are inserted, doing it by hand is slow and error-prone.

This article uses Spire.XLS for Python to show how to insert an image at a specific cell, adjust its offset within the cell, read its position and size, compress it to reduce file size, and delete images from a worksheet in bulk.

Setting Up the Environment

Install the Spire.XLS library:

pip install Spire.XLS

Then import the required modules in your script:

from spire.xls import *
from spire.xls.common import *

Inserting an Image at a Specific Cell

Worksheet.Pictures.Add() inserts an image at a cell location. The first two arguments are the row and column numbers, and the third is the image path:

workbook = Workbook()
workbook.LoadFromFile("report.xlsx")
sheet = workbook.Worksheets[0]

# Insert an image at row 14, column 5 (i.e. E14)
sheet.Pictures.Add(14, 5, "logo.png")

workbook.SaveToFile("InsertImage.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

The image is inserted at its original size, with its top-left corner aligned to the specified cell. If the image is larger than the cell, it overlaps neighboring cells. To avoid overlap, adjust the target column width and row height before inserting the image.

Adjusting the Image Offset Within a Cell

After insertion, LeftColumnOffset and TopRowOffset fine-tune the image position inside the cell, leaving a gap between the image and the cell borders:

workbook = Workbook()
sheet = workbook.Worksheets[0]

sheet.Range["A1"].Text = "Align picture within a cell:"
sheet.Range["A1"].Style.VerticalAlignment = VerticalAlignType.Top

picture = sheet.Pictures.Add(1, 1, "logo.png")

# Widen the column and heighten the row to fit the image
sheet.Columns[0].ColumnWidth = 40
sheet.Rows[0].RowHeight = 200

# Offset the image inside the cell
picture.LeftColumnOffset = 100
picture.TopRowOffset = 25

workbook.SaveToFile("AlignImage.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

LeftColumnOffset is the horizontal offset from the cell's left edge, and TopRowOffset is the vertical offset from the top edge, both in pixels. Combined with ColumnWidth and RowHeight to enlarge the cell first, then offsetting the image into place, you can center the image or leave whitespace around it.

Reading the Image Position and Size

An image already in a worksheet can be retrieved by index from the Pictures collection, and its position and dimensions read back:

workbook = Workbook()
workbook.LoadFromFile("WithImage.xlsx")
sheet = workbook.Worksheets[0]

picture = sheet.Pictures[0]
left = picture.Left
top = picture.Top
width = picture.Width
height = picture.Height

print(f"Left={left}, Top={top}, Width={width}, Height={height}")

workbook.Dispose()

Left and Top are the absolute coordinates of the image in the worksheet, and Width and Height are its displayed dimensions. These values are useful when aligning an image to a region or checking whether it falls outside the print area.

Compressing Images

Inserting high-resolution images quickly inflates the Excel file size. The Compress() method compresses images in a worksheet at a specified quality. The argument is an integer from 0 to 100; a smaller value means higher compression:

workbook = Workbook()
workbook.LoadFromFile("LargeImages.xlsx")

for sheet in workbook.Worksheets:
    for picture in sheet.Pictures:
        picture.Compress(50)

workbook.SaveToFile("Compressed.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

The outer loop iterates all worksheets, the inner loop all images on each sheet. Compress(50) reduces every image to 50% quality. For reports viewed only on screen, 50 is usually enough; for reports that will be printed, 75 preserves more detail.

Deleting Images from a Worksheet

To clean old images out of a template or remove unwanted illustrations, iterate the Pictures collection and remove each one:

workbook = Workbook()
workbook.LoadFromFile("Template.xlsx")
sheet = workbook.Worksheets[0]

# Iterate in reverse to avoid index shifting after removal
for i in range(sheet.Pictures.Count - 1, -1, -1):
    sheet.Pictures[i].Remove()

workbook.SaveToFile("Deleted.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

Iterate from the end when deleting. Each Remove() shortens the collection by one, so a forward loop would skip images or go out of bounds. A reverse loop safely clears every image on the sheet.

Practical Tips

• Set the target cell's column width and row height before inserting an image, so it does not overlap neighboring data.
• LeftColumnOffset and TopRowOffset are in pixels, while ColumnWidth is in character units — do not mix them.
• Compress() modifies the image data itself and is lossy; back up the original image first if it must be preserved.
• To insert the same logo into multiple worksheets, put Pictures.Add() inside a for sheet in workbook.Worksheets loop.
• Call workbook.Dispose() when finished to release resources.

Conclusion

This article covered the common operations for working with images in Excel using Python: inserting an image at a specific cell with Pictures.Add(), fine-tuning its position with LeftColumnOffset and TopRowOffset, reading its position and size through Left/Top/Width/Height, reducing file size with Compress(), and deleting images in bulk by iterating the Pictures collection in reverse. Combined inside a report-generation script, image insertion and maintenance can be fully automated.