{"id":2325,"date":"2026-09-23T07:44:28","date_gmt":"2026-09-22T23:44:28","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2325"},"modified":"2026-03-28T13:16:48","modified_gmt":"2026-03-28T13:16:48","slug":"how-to-use-worksheethpagebreaks-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheethpagebreaks-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.HPageBreaks in the xlwings API way"},"content":{"rendered":"\n

The HPageBreaks<\/strong> member of the Worksheet<\/strong> object in the Excel object model provides access to the collection of horizontal page breaks within a worksheet. In xlwings, this collection is accessible via the api<\/code> property, which exposes the underlying Excel VBA object model. This allows for programmatic control over where pages break when the worksheet is printed, enabling precise formatting for reports and documents. The primary use is to add, delete, or query horizontal page breaks, which are essential for managing print layout in multi-page data sets.<\/p>\n\n\n\n

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

In xlwings, you access the HPageBreaks<\/code> collection through a worksheet object’s api<\/code> property:<\/p>\n\n\n\n

hpagebreaks = ws.api.HPageBreaks<\/code><\/pre>\n\n\n\n
The collection is 1-indexed, similar to Excel VBA. Key methods and properties include:<\/p>\n\n\n\n
    \n
  • Add(Before)<\/code><\/strong>: Adds a new horizontal page break.<\/li>\n\n\n\n
  • Before<\/code>: A required parameter of type Object<\/code>. It specifies the range above which the page break will be inserted. You typically pass an xlwings Range<\/code> object’s .api<\/code> property (e.g., ws.range(\"A10\").api<\/code>). The break is inserted above the top edge of this range.<\/li>\n\n\n\n
  • Count<\/code><\/strong> (Property): Returns a Long<\/code> representing the number of horizontal page breaks in the collection.<\/li>\n\n\n\n
  • Item(Index)<\/code><\/strong>: Returns a single HPageBreak<\/code> object from the collection.<\/li>\n\n\n\n
  • Index<\/code>: The index number of the page break (1-indexed).<\/li>\n\n\n\n
  • Location<\/code><\/strong> (Property of an HPageBreak<\/code> object): Returns a Range<\/code> object representing the cell where the page break is set (the cell immediately below the break line). This is read\/write, allowing you to move an existing break.<\/li>\n<\/ul>\n\n\n\n
    Code Examples<\/strong><\/p>\n\n\n\n
      \n
    1. Adding a Horizontal Page Break:<\/strong>
      Inserts a horizontal page break above row 15.<\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\nwb = xw.Book(\"report.xlsx\")\nws = wb.sheets[\"Sheet1\"]\n# Add a page break above cell A15\nws.api.HPageBreaks.Add(Before=ws.range(\"A15\").api)<\/code><\/pre>\n\n\n\n
        \n
      1. Counting and Listing Page Breaks:<\/strong>
        Prints the count and location of each horizontal page break.<\/li>\n<\/ol>\n\n\n\n
        import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets[0]\nhbreaks = ws.api.HPageBreaks\nprint(f\"Number of horizontal page breaks: {hbreaks.Count}\")\nfor i in range(1, hbreaks.Count + 1):\n    break_obj = hbreaks.Item(i)\n    # The Location property returns the cell below the break\n    location_cell = break_obj.Location.Address\n    print(f\" Break {i}: Above row {break_obj.Location.Row} (at {location_cell})\")<\/code><\/pre>\n\n\n\n
          \n
        1. Deleting All Horizontal Page Breaks:<\/strong>
          Clears all manually set horizontal page breaks from the sheet. Note: This does not remove automatic breaks inserted by Excel based on page margins and size.<\/li>\n<\/ol>\n\n\n\n
          import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets[0]\nhbreaks = ws.api.HPageBreaks\n# Loop backwards to avoid index shifting when deleting\nfor i in range(hbreaks.Count, 0, -1):\n    # The HPageBreak object itself doesn't have a .Delete() method.\n    # You delete it by clearing the break from its location.\n    hbreaks.Item(i).Location.PageBreak = -4142 # xlPageBreakNone\n    # Alternatively, reset all page breaks on the sheet:\n    # ws.api.ResetAllPageBreaks()<\/code><\/pre>\n\n\n\n
            \n
          1. Moving an Existing Page Break:<\/strong>
            Changes the position of the first horizontal page break to be above row 25.<\/li>\n<\/ol>\n\n\n\n
            import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets[0]\nhbreaks = ws.api.HPageBreaks\nif hbreaks.Count >= 1:\n    first_break = hbreaks.Item(1)\n    first_break.Location = ws.range(\"A25\").api<\/code><\/pre>\n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            The **HPageBreaks** member of the **Worksheet** object in the Excel object model provides access to …<\/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-2325","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2325","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=2325"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2325\/revisions"}],"predecessor-version":[{"id":3557,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2325\/revisions\/3557"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2325"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2325"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2325"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}