{"id":2274,"date":"2026-08-28T15:22:25","date_gmt":"2026-08-28T07:22:25","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2274"},"modified":"2026-03-28T12:13:50","modified_gmt":"2026-03-28T12:13:50","slug":"how-to-use-worksheetchartobjects-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetchartobjects-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.ChartObjects in the xlwings API way"},"content":{"rendered":"\n

The ChartObjects<\/code> member of a Worksheet<\/code> object in Excel’s object model represents a collection of all embedded chart objects (charts that are placed directly on a worksheet, as opposed to chart sheets). In xlwings, this collection is accessible via the api<\/code> property, which provides direct access to the underlying COM object model. This allows for detailed control over chart creation, modification, and management directly from Python.<\/p>\n\n\n\n

Functionality:<\/strong>
The primary function of the ChartObjects<\/code> collection is to enable programmatic manipulation of charts embedded within a specific worksheet. Through xlwings, you can add new charts, access existing ones, modify their properties (such as position, size, and chart type), or delete them. This is particularly useful for automating report generation, dynamically updating visualizations based on data changes, or creating dashboards where charts need to be precisely positioned alongside data.<\/p>\n\n\n\n

Syntax:<\/strong>
In xlwings, you access the ChartObjects<\/code> collection via the api<\/code> property of a Sheet<\/code> object (which corresponds to a worksheet). The typical syntax is:<\/p>\n\n\n\n

chart_objects = ws.api.ChartObjects<\/code><\/pre>\n\n\n\n
Here, ws<\/code> is an xlwings Sheet<\/code> object representing the worksheet. The ChartObjects<\/code> object has several methods and properties. A key method for adding a new chart is Add<\/code>, which has the following parameters:<\/p>\n\n\n\n
    \n
  • Left<\/code> (Required, float<\/code>): The position, in points, of the left edge of the new chart object relative to the left edge of column A on the worksheet.<\/li>\n\n\n\n
  • Top<\/code> (Required, float<\/code>): The position, in points, of the top edge of the new chart object relative to the top edge of row 1.<\/li>\n\n\n\n
  • Width<\/code> (Required, float<\/code>): The width of the new chart object in points.<\/li>\n\n\n\n
  • Height<\/code> (Required, float<\/code>): The height of the new chart object in points.<\/li>\n<\/ul>\n\n\n\n
    The method returns a ChartObject<\/code> object, which has a Chart<\/code> property that provides access to the actual chart (where you set the chart type, data source, etc.).<\/p>\n\n\n\n
    Code Examples:<\/strong><\/p>\n\n\n\n
      \n
    1. Adding a New Chart:<\/strong><\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\n\n# Connect to an existing workbook or create a new one\nwb = xw.Book() # Creates a new workbook\nws = wb.sheets['Sheet1']\n\n# Add some sample data\nws.range('A1').value = [['Month', 'Sales'], ['Jan', 150], ['Feb', 200], ['Mar', 180]]\n\n# Access the ChartObjects collection and add a new chart\nchart_obj = ws.api.ChartObjects().Add(Left=100, Top=50, Width=300, Height=200)\nchart = chart_obj.Chart\n\n# Set the chart type and data source\nchart.ChartType = 51 # xlColumnClustered (value from Excel constants)\nchart.SetSourceData(Source=ws.range('A1:B4').api)\nchart.HasTitle = True\nchart.ChartTitle.Text = \"Monthly Sales\"<\/code><\/pre>\n\n\n\n
        \n
      1. Accessing and Modifying an Existing Chart:<\/strong>
        Assume there is already an embedded chart named “Chart 1” on the worksheet.<\/li>\n<\/ol>\n\n\n\n
        # Access the ChartObjects collection\nall_charts = ws.api.ChartObjects\n\n# Access a specific chart by its index (1-based) or name\nchart_obj = all_charts(1) # First chart in the collection\n# Or by name: chart_obj = all_charts(\"Chart 1\")\n\n# Modify its position and size\nchart_obj.Left = 200\nchart_obj.Top = 100\nchart_obj.Width = 400\nchart_obj.Height = 250\n\n# Change the chart title via the Chart property\nchart_obj.Chart.ChartTitle.Text = \"Updated Sales Report\"<\/code><\/pre>\n\n\n\n
          \n
        1. Looping Through All Charts on a Worksheet:<\/strong><\/li>\n<\/ol>\n\n\n\n
          # Iterate over all embedded chart objects\nfor chart_obj in ws.api.ChartObjects:\nprint(f\"Chart Name: {chart_obj.Name}\")\nprint(f\"Chart Type: {chart_obj.Chart.ChartType}\")\n# You can perform operations like checking title or changing data series\nif chart_obj.Chart.HasTitle:\n    print(f\"Title: {chart_obj.Chart.ChartTitle.Text}\")<\/code><\/pre>\n\n\n\n
            \n
          1. Deleting a Chart:<\/strong><\/li>\n<\/ol>\n\n\n\n
            # Delete a specific chart by name\nws.api.ChartObjects(\"Chart 1\").Delete()\n# Or delete all charts on the worksheet\nfor chart_obj in ws.api.ChartObjects:\n    chart_obj.Delete()<\/code><\/pre>\n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            The `ChartObjects` member of a `Worksheet` object in Excel's object model represents a collection of…<\/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-2274","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2274","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=2274"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2274\/revisions"}],"predecessor-version":[{"id":3472,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2274\/revisions\/3472"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2274"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2274"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2274"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}