{"id":2267,"date":"2026-08-25T07:07:02","date_gmt":"2026-08-24T23:07:02","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2267"},"modified":"2026-03-28T12:07:52","modified_gmt":"2026-03-28T12:07:52","slug":"how-to-use-worksheetshpagebreaks-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetshpagebreaks-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheets.HPageBreaks in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The HPageBreaks collection in the Worksheets object represents the horizontal page breaks within a worksheet, allowing developers to programmatically control where pages are divided when printing. This feature is crucial for creating print-ready reports and ensuring that data is logically segmented across pages. In xlwings, you can access the HPageBreaks collection via a Worksheet object, enabling you to add, remove, or modify horizontal page breaks based on specific rows. This functionality enhances automation in Excel tasks, such as generating formatted printouts from dynamic datasets.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Functionality<\/strong>: The HPageBreaks member provides methods to manage horizontal page breaks, which determine the row positions where a new page starts during printing. You can insert breaks to avoid splitting critical data across pages, adjust existing breaks for better layout, or clear all breaks for a continuous print. This is particularly useful for reports with tables, charts, or grouped data that require precise pagination.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax<\/strong>: In xlwings, you access HPageBreaks through a worksheet object. The key method for adding a break is <code>add()<\/code>, which inserts a horizontal page break above a specified row. The syntax is as follows:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>ws.api.HPageBreaks.Add(Before)<\/code><br>Here, <code>Before<\/code> is a required parameter that specifies the row above which the page break is inserted. It must be a row number (integer), and the break will be placed between the previous row and this row. For example, setting <code>Before=10<\/code> adds a break between rows 9 and 10. To remove all horizontal page breaks, you can use <code>ws.api.HPageBreaks.Delete()<\/code>.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example<\/strong>: Suppose you have an Excel workbook with a worksheet named &#8220;SalesData&#8221; and you want to insert horizontal page breaks after every 20 rows to ensure each page contains a consistent block of data. Below is an xlwings code example that demonstrates this:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active workbook and specify the worksheet\nwb = xw.Book(\"example.xlsx\")\nws = wb.sheets&#91;\"SalesData\"]\n\n# Clear any existing horizontal page breaks to start fresh\nws.api.HPageBreaks.Delete()\n\n# Insert horizontal page breaks after every 20 rows, starting from row 21\nfor row in range(21, ws.api.UsedRange.Rows.Count + 1, 20):\n    ws.api.HPageBreaks.Add(Before=row)\n\n# Save and close the workbook\nwb.save()\nwb.close()<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The HPageBreaks collection in the Worksheets object represents the horizontal page breaks within a w&#8230;<\/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-2267","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2267","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=2267"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2267\/revisions"}],"predecessor-version":[{"id":3462,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2267\/revisions\/3462"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2267"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2267"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2267"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}