worksheet.insert_image()  参考

insert_image(rowcolimage[, options])

Insert an image in a worksheet cell.

  • row (int) – The cell row (zero indexed).
  • col (int) – The cell column (zero indexed).
  • image (string) – Image filename (with path if required).
  • options (dict) – Optional parameters for image position, scale and url.

0: Success.


-1: Row or column is out of worksheet bounds.

This method can be used to insert a image into a worksheet. The image can be in PNG, JPEG, BMP, WMF or EMF format (see the notes about BMP and EMF below):

worksheet.insert_image('B2', 'python.png')


Both row-column and A1 style notation are supported. The following are equivalent:

worksheet.insert_image(1, 1, 'python.png')
worksheet.insert_image('B2', 'python.png')

See Working with Cell Notation for more details.

A file path can be specified with the image name:

worksheet1.insert_image('B10', '../images/python.png')
worksheet2.insert_image('B20', r'c:\images\python.png')

The insert_image() method takes optional parameters in a dictionary to position and scale the image. The available parameters with their default values are:

    'x_offset':    0,
    'y_offset':    0,
    'x_scale':     1,
    'y_scale':     1,
    'url':         None,
    'tip':         None,
    'image_data':  None,
    'positioning': None,

The offset values are in pixels:

worksheet1.insert_image('B2', 'python.png', {'x_offset': 15, 'y_offset': 10})

The offsets can be greater than the width or height of the underlying cell. This can be occasionally useful if you wish to align two or more images relative to the same cell.

The x_scale and y_scale parameters can be used to scale the image horizontally and vertically:

worksheet.insert_image('B3', 'python.png', {'x_scale': 0.5, 'y_scale': 0.5})

The url parameter can used to add a hyperlink/url to the image. The tip parameter gives an option mouseover tooltip for images with hyperlinks:

worksheet.insert_image('B4', 'python.png', {'url': 'https://python.org'})

See also write_url() for details on supported URIs.

The image_data parameter is used to add an in-memory byte stream in io.BytesIO format:

worksheet.insert_image('B5', 'python.png', {'image_data': image_data})

This is generally used for inserting images from URLs:

url = 'https://python.org/logo.png'
image_data = io.BytesIO(urllib2.urlopen(url).read())

worksheet.insert_image('B5', url, {'image_data': image_data})

When using the image_data parameter a filename must still be passed to insert_image() since it is required by Excel. In the previous example the filename is extracted from the URL string. See also Example: Inserting images from a URL or byte stream into a worksheet.

The positioning parameter can be used to control the object positioning of the image:

worksheet.insert_image('B3', 'python.png', {'positioning': 1})

Where positioning has the following allowable values:

  1. Move and size with cells.
  2. Move but don’t size with cells (the default).
  3. Don’t move or size with cells.


The scaling of a image may be affected if is crosses a row that has its default height changed due to a font that is larger than the default font size or that has text wrapping turned on. To avoid this you should explicitly set the height of the row using set_row() if it crosses an inserted image.


BMP images are only supported for backward compatibility. In general it is best to avoid BMP images since they aren’t compressed. If used, BMP images must be 24 bit, true color, bitmaps.


EMF images can have very small differences in width and height when compared to Excel files. Despite a lot of effort and testing it wasn’t possible to match exactly Excel’s calculations for handling the dimensions of EMF files. However, the differences are are small (< 1%) and in general aren’t visible.

See also Example: Inserting images into a worksheet.


©️2020 CSDN 皮肤主题: 编程工作室 设计师:CSDN官方博客 返回首页