{"id":2333,"date":"2026-09-27T07:06:55","date_gmt":"2026-09-26T23:06:55","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2333"},"modified":"2026-03-28T13:16:04","modified_gmt":"2026-03-28T13:16:04","slug":"how-to-use-worksheetoutline-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetoutline-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.Outline in the xlwings API way"},"content":{"rendered":"\n

The Outline<\/code> property of a Worksheet<\/code> object in Excel provides access to the outlining (grouping and ungrouping) features for rows and columns on a sheet. Outlining allows you to collapse or expand sections of data, making it easier to manage and view large datasets by hiding detail rows or columns while showing summary information. In xlwings, you can control these outlining features programmatically through the api<\/code> property, which exposes the underlying Excel object model.<\/p>\n\n\n\n

Syntax and Parameters<\/strong><\/p>\n\n\n\n

In xlwings, you access the Outline<\/code> property via the api<\/code> property of a Worksheet<\/code> object. The general syntax is:<\/p>\n\n\n\n

worksheet.api.Outline<\/code><\/pre>\n\n\n\n
This returns an Outline<\/code> object, which has several key methods and properties for managing outlines. The most commonly used methods include:<\/p>\n\n\n\n
    \n
  • ShowLevels(row_levels, column_levels)<\/code>: This method sets the outline levels to display.<\/li>\n\n\n\n
  • row_levels<\/code> (optional): An integer specifying the row outline level to show. If omitted, the current row level is unchanged. Levels typically range from 1 (highest summary) to 8 (most detailed).<\/li>\n\n\n\n
  • column_levels<\/code> (optional): An integer specifying the column outline level to show. If omitted, the current column level is unchanged.<\/li>\n\n\n\n
  • AutomaticStyles<\/code>: A property that, when set to True<\/code>, allows Excel to apply automatic styles to summary rows and columns. You can set it using worksheet.api.Outline.AutomaticStyles = True<\/code>.<\/li>\n\n\n\n
  • SummaryRow<\/code> and SummaryColumn<\/code>: Properties that control the placement of summary rows and columns relative to the detail data. For example, xlAbove<\/code> (or -4162<\/code> as a constant) places summaries above details, while xlBelow<\/code> (or -4167<\/code>) places them below. In xlwings, you can use constants from the xlwings.constants<\/code> module or their numeric equivalents.<\/li>\n<\/ul>\n\n\n\n
    Code Examples<\/strong><\/p>\n\n\n\n
    Here are practical examples using xlwings to manipulate worksheet outlines:<\/p>\n\n\n\n
      \n
    1. Setting Outline Levels<\/strong>: To collapse all rows to show only the top-level summary (level 1) and all columns to show full detail (level 8), you can use:<\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\nwb = xw.Book(\"example.xlsx\")\nws = wb.sheets[\"Sheet1\"]\nws.api.Outline.ShowLevels(row_levels=1, column_levels=8)<\/code><\/pre>\n\n\n\n
        \n
      1. Enabling Automatic Styles<\/strong>: To apply Excel’s automatic outlining styles for better visual distinction:<\/li>\n<\/ol>\n\n\n\n
        ws.api.Outline.AutomaticStyles = True<\/code><\/pre>\n\n\n\n
          \n
        1. Configuring Summary Row Placement<\/strong>: To set summary rows to appear below the detail data (commonly used for subtotals), you can set the SummaryRow<\/code> property. Using xlwings constants:<\/li>\n<\/ol>\n\n\n\n
          from xlwings.constants import xlBelow\nws.api.Outline.SummaryRow = xlBelow<\/code><\/pre>\n\n\n\n
          Alternatively, with a numeric value:<\/p>\n\n\n\n
          ws.api.Outline.SummaryRow = -4167 # Equivalent to xlBelow<\/code><\/pre>\n\n\n\n
            \n
          1. Grouping Rows Programmatically<\/strong>: While the Outline<\/code> property itself doesn’t group data directly, you can use it in conjunction with Excel’s Range<\/code> objects. For instance, to group rows 5 through 10 and apply outlining:<\/li>\n<\/ol>\n\n\n\n
            ws.range(\"5:10\").api.Group()\n# After grouping, you can control the outline level\nws.api.Outline.ShowLevels(row_levels=1)<\/code><\/pre>\n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            The `Outline` property of a `Worksheet` object in Excel provides access to the outlining (grouping a…<\/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-2333","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2333","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=2333"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2333\/revisions"}],"predecessor-version":[{"id":3555,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2333\/revisions\/3555"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2333"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2333"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2333"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}