{"id":2229,"date":"2026-08-06T07:36:47","date_gmt":"2026-08-05T23:36:47","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2229"},"modified":"2026-03-28T11:37:06","modified_gmt":"2026-03-28T11:37:06","slug":"how-to-use-workbooksadd-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-workbooksadd-in-the-xlwings-api-way\/","title":{"rendered":"How to use Workbooks.Add in the xlwings API way"},"content":{"rendered":"\n

The Add<\/code> member of the Workbooks<\/code> object in the Excel object model is a method used to create a new, empty workbook. In xlwings, this functionality is accessed through the xlwings.Book()<\/code> constructor, which internally leverages the Add<\/code> method when creating a new workbook without opening an existing file. This is a fundamental operation for automating report generation, data processing workflows, or any task that requires starting with a fresh Excel file programmatically.<\/p>\n\n\n\n

Functionality<\/strong>
The primary purpose is to instantiate a new Excel workbook. This new workbook becomes the active workbook in the Excel application and contains a default number of worksheets (typically one, depending on Excel’s default settings). It provides a clean slate for subsequent operations like data entry, formatting, or chart creation.<\/p>\n\n\n\n

Syntax and Parameters<\/strong>
In xlwings, you do not call Add<\/code> directly on a Workbooks<\/code> collection. Instead, you create a new Book<\/code> object. The equivalent action is performed with the following syntax:<\/p>\n\n\n\n

import xlwings as xw\nnew_workbook = xw.Book()<\/code><\/pre>\n\n\n\n
This constructor corresponds to the VBA Workbooks.Add()<\/code> method. The xlwings Book()<\/code> constructor can also accept a template<\/code> argument to create a workbook based on an existing template file.<\/p>\n\n\n\n
    \n
  • template<\/code><\/strong> (optional, string): The full path to an Excel template file (.xltx<\/code>, .xltm<\/code>). If provided, the new workbook is created as a copy of this template. If omitted, a new blank workbook is created based on the default workbook template.<\/li>\n<\/ul>\n\n\n\n
    Code Examples<\/strong><\/p>\n\n\n\n
      \n
    1. Creating a Blank Workbook:<\/strong>
      This is the most straightforward use case. The code below starts Excel (if not already running), creates a new workbook, and returns a Book<\/code> object linked to it.<\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\n\n# Create a new blank workbook\nwb = xw.Book()\nprint(f\"New workbook created: {wb.name}\")\n\n# Add data to the first worksheet\nwb.sheets[0].range('A1').value = \"Sample Data\"\nwb.sheets[0].range('A2').value = 100\n\n# Save the workbook\nwb.save(r'C:\\path\\to\\NewReport.xlsx')\nwb.close()<\/code><\/pre>\n\n\n\n
        \n
      1. Creating a Workbook from a Template:<\/strong>
        This is useful for standardized reports where formatting, headers, or specific sheet structures are pre-defined in a template file.<\/li>\n<\/ol>\n\n\n\n
        import xlwings as xw\n\n# Path to your template file\ntemplate_path = r'C:\\templates\\Monthly_Report_Template.xltx'\n\n# Create a new workbook based on the template\nwb = xw.Book(template_path)\nprint(f\"Workbook created from template: {wb.name}\")\n\n# The new workbook inherits all sheets and formatting from the template.\n# You can now populate it with data.\nwb.sheets['Data'].range('B5').value = \"Q4 Results\"\n# ... additional data processing ...\n\n# Save it as a regular workbook\nwb.save(r'C:\\reports\\Monthly_Report_November.xlsx')<\/code><\/pre>\n\n\n\n
        <\/p>\n","protected":false},"excerpt":{"rendered":"
        The `Add` member of the `Workbooks` object in the Excel object model is a method used to create a ne…<\/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-2229","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2229","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=2229"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2229\/revisions"}],"predecessor-version":[{"id":3407,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2229\/revisions\/3407"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2229"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2229"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2229"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}