{"id":2357,"date":"2026-10-09T07:27:39","date_gmt":"2026-10-08T23:27:39","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2357"},"modified":"2026-03-29T09:51:29","modified_gmt":"2026-03-29T09:51:29","slug":"how-to-use-worksheetvpagebreaks-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetvpagebreaks-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.VPageBreaks in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <strong>VPageBreaks<\/strong> member of a <strong>Worksheet<\/strong> object in Excel&#8217;s object model represents the collection of vertical page breaks within the sheet. In xlwings, this collection is accessible via the <code>api<\/code> property, allowing you to programmatically manage where pages are divided when printing. This is particularly useful for creating custom print layouts, ensuring that data is segmented logically across multiple pages without manual adjustment. The <strong>VPageBreaks<\/strong> collection contains <strong>VPageBreak<\/strong> objects, each representing a single vertical page break.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax in xlwings:<\/strong><br>To access the <strong>VPageBreaks<\/strong> collection in xlwings, use the following pattern:<br><code>worksheet.api.VPageBreaks<\/code><br>Here, <code>worksheet<\/code> is an xlwings <strong>Sheet<\/strong> object. The <strong>VPageBreaks<\/strong> collection supports methods and properties for adding, counting, and retrieving vertical page breaks. Key members include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Add(Before)<\/strong>: Adds a new vertical page break. The <code>Before<\/code> parameter is a required argument of type <strong>Object<\/strong>, specifying the column to the left of which the break is inserted. In xlwings, you typically pass an Excel <strong>Range<\/strong> object representing the column (e.g., <code>worksheet.range(\"C1\").api<\/code> to insert a break before column C).<\/li>\n\n\n\n<li><strong>Count<\/strong>: A read-only property that returns the number of vertical page breaks in the collection (integer).<\/li>\n\n\n\n<li><strong>Item(Index)<\/strong>: Returns a single <strong>VPageBreak<\/strong> object from the collection. The <code>Index<\/code> parameter is the break number, starting from 1 for the leftmost break.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example Usage with xlwings:<\/strong><br>Below are code examples demonstrating how to use <strong>VPageBreaks<\/strong> in xlwings for common tasks. Ensure you have an Excel workbook open and referenced via xlwings.<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Adding a Vertical Page Break:<\/strong><br>This example inserts a vertical page break before column D (i.e., between columns C and D) on the active sheet.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\nwb = xw.Book.active # Assume an active workbook\nws = wb.sheets.active\n# Add a vertical page break before column D\nws.api.VPageBreaks.Add(Before=ws.range(\"D1\").api)\nprint(\"Vertical page break added before column D.\")<\/code><\/pre>\n\n\n\n<ol start=\"2\" class=\"wp-block-list\">\n<li><strong>Counting Vertical Page Breaks:<\/strong><br>This snippet counts and displays the total vertical page breaks in the worksheet.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets.active\nbreak_count = ws.api.VPageBreaks.Count\nprint(f\"Number of vertical page breaks: {break_count}\")<\/code><\/pre>\n\n\n\n<ol start=\"3\" class=\"wp-block-list\">\n<li><strong>Iterating Through and Removing Vertical Page Breaks:<\/strong><br>This example loops through all vertical page breaks and removes each one, clearing manual break settings.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets.active\nvpage_breaks = ws.api.VPageBreaks\n# Iterate in reverse to avoid index issues when deleting\nfor i in range(vpage_breaks.Count, 0, -1):\n    vbreak = vpage_breaks.Item(i)\n    vbreak.Delete() # Remove the page break\n    print(\"All vertical page breaks have been removed.\")<\/code><\/pre>\n\n\n\n<ol start=\"4\" class=\"wp-block-list\">\n<li><strong>Accessing a Specific Page Break&#8217;s Location:<\/strong><br>This code retrieves the leftmost vertical page break and prints its column location.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\nwb = xw.Book.active\nws = wb.sheets.active\nif ws.api.VPageBreaks.Count > 0:\n    first_vbreak = ws.api.VPageBreaks.Item(1)\n    # The Location property returns a Range object for the column to the left of the break\n    break_location = first_vbreak.Location.Column\n    print(f\"The first vertical page break is before column: {break_location}\")\nelse:\n    print(\"No vertical page breaks exist.\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The **VPageBreaks** member of a **Worksheet** object in Excel&apos;s object model represents the collecti&#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-2357","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2357","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=2357"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2357\/revisions"}],"predecessor-version":[{"id":3593,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2357\/revisions\/3593"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2357"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2357"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2357"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}