{"id":2347,"date":"2026-10-04T07:02:56","date_gmt":"2026-10-03T23:02:56","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2347"},"modified":"2026-03-29T09:42:53","modified_gmt":"2026-03-29T09:42:53","slug":"how-to-use-worksheetshapes-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetshapes-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.Shapes in the xlwings API way"},"content":{"rendered":"\n

In Excel, the Shapes<\/code> collection of a Worksheet<\/code> object contains all the shape objects on the sheet, such as rectangles, lines, text boxes, pictures, charts, and other drawing objects. Through xlwings, you can programmatically access and manipulate these shapes, enabling automation of tasks like adding annotations, inserting logos, or modifying chart elements. The Shapes<\/code> member provides methods to add new shapes, iterate through existing ones, and control their properties, making it a powerful tool for enhancing the visual appeal and functionality of Excel reports.<\/p>\n\n\n\n

The xlwings API for accessing the Shapes<\/code> collection is straightforward. You can reference it via a Worksheet<\/code> object. The syntax is:<\/p>\n\n\n\n

worksheet.shapes<\/code><\/pre>\n\n\n\n
This returns a Shapes<\/code> collection object. Key methods and properties include:<\/p>\n\n\n\n
    \n
  • add_shape(shape_type, left, top, width, height)<\/code>: Adds a new shape. Parameters: shape_type<\/code> (integer, e.g., 1 for rectangle, 9 for oval), left<\/code> and top<\/code> (distance from left\/top edges in points), width<\/code> and height<\/code> (in points).<\/li>\n\n\n\n
  • count<\/code>: Property that returns the number of shapes on the worksheet.<\/li>\n\n\n\n
  • item(index)<\/code>: Returns a specific shape by index (1-based) or name.<\/li>\n\n\n\n
  • Iteration: You can loop through shapes using a for<\/code> loop.<\/li>\n<\/ul>\n\n\n\n
    Common shape types (MsoAutoShapeType enumeration from Microsoft documentation) include:<\/p>\n\n\n\n
    Value<\/th>Shape Type<\/th><\/tr><\/thead>
    1<\/td>Rectangle<\/td><\/tr>
    5<\/td>Rounded Rectangle<\/td><\/tr>
    9<\/td>Oval<\/td><\/tr>
    13<\/td>Line<\/td><\/tr>
    17<\/td>Text Box<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    For example, to add a red rectangle and a text box to a worksheet, and then list all shapes:<\/p>\n\n\n\n
    import xlwings as xw\n\n# Connect to an existing workbook and worksheet\nwb = xw.Book('example.xlsx')\nws = wb.sheets['Sheet1']\n\n# Add a rectangle shape\nrect = ws.shapes.add_shape(1, left=50, top=50, width=100, height=50)\nrect.api.Fill.ForeColor.RGB = 0xFF0000 # Set fill color to red via the underlying API\n\n# Add a text box\ntext_box = ws.shapes.add_shape(17, left=200, top=50, width=150, height=30)\ntext_box.text = \"Sample Text\" # Set text content\n\n# Count and iterate through shapes\nprint(f\"Total shapes: {ws.shapes.count}\")\nfor shape in ws.shapes:\n    print(f\"Shape name: {shape.name}, type ID: {shape.api.AutoShapeType}\")\n\n# Modify an existing shape by index\nif ws.shapes.count > 0:\n    first_shape = ws.shapes[0] # Access by index (0-based in xlwings)\n    first_shape.left = 10 # Move it horizontally\n\n# Save changes\nwb.save()<\/code><\/pre>\n\n\n\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    In Excel, the `Shapes` collection of a `Worksheet` object contains all the shape objects on the shee…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2347","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2347","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2347"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2347\/revisions"}],"predecessor-version":[{"id":3578,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2347\/revisions\/3578"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2347"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2347"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2347"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}