{"id":2240,"date":"2026-08-11T15:58:29","date_gmt":"2026-08-11T07:58:29","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2240"},"modified":"2026-03-28T11:46:17","modified_gmt":"2026-03-28T11:46:17","slug":"how-to-use-workbooksitem-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-workbooksitem-in-the-xlwings-api-way\/","title":{"rendered":"How to use Workbooks.Item in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <code>Item<\/code> member of the <code>Workbooks<\/code> object in Excel&#8217;s object model is a property used to access a specific workbook within the <code>Workbooks<\/code> collection. In xlwings, this functionality is typically accessed through the <code>books<\/code> property of the <code>App<\/code> object, which represents the collection of open workbooks. The <code>Item<\/code> property allows you to retrieve a workbook by its index number (position in the collection) or by its name (as a string). This is essential for programmatically manipulating specific workbooks when multiple workbooks are open, enabling you to set a workbook as the active object, read data, or perform other operations.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax in xlwings:<\/strong><br>While xlwings does not explicitly expose an <code>Item<\/code> method, the <code>books<\/code> collection behaves similarly. You can access a workbook using indexing or key-based lookup.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>By index (1-based, like Excel VBA): <code>app.books[index]<\/code><\/li>\n\n\n\n<li>By name (workbook filename): <code>app.books[name]<\/code><\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Parameters:<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>index<\/code>: An integer representing the position of the workbook in the <code>books<\/code> collection. The index starts at 1 for the first workbook opened or referenced.<\/li>\n\n\n\n<li><code>name<\/code>: A string that matches the full name (including extension) of the workbook, such as &#8220;Data.xlsx&#8221;. If the workbook is saved, you can use the base name without the path if it&#8217;s unique among open workbooks.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Examples:<\/strong><\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Access by Index:<\/strong><br>Suppose you have two workbooks open: &#8220;Report.xlsx&#8221; (opened first) and &#8220;Analysis.xlsx&#8221; (opened second). To reference the first workbook:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\napp = xw.apps.active # Get the active Excel application\nfirst_workbook = app.books&#91;0] # Index 0 in xlwings corresponds to VBA's Item(1)\nprint(first_workbook.name) # Output: Report.xlsx<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Note: xlwings uses 0-based indexing for collections in Python, unlike VBA&#8217;s 1-based <code>Item<\/code>. So <code>app.books[0]<\/code> is equivalent to <code>Workbooks.Item(1)<\/code> in VBA.<\/p>\n\n\n\n<ol start=\"2\" class=\"wp-block-list\">\n<li><strong>Access by Name:<\/strong><br>To directly access a workbook named &#8220;Financials.xlsx&#8221;:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\napp = xw.apps.active\ntarget_workbook = app.books&#91;'Financials.xlsx']\ntarget_workbook.activate() # Make it the active workbook<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If multiple workbooks have similar names, ensure you use the full filename. This method is case-insensitive on Windows but case-sensitive on macOS.<\/p>\n\n\n\n<ol start=\"3\" class=\"wp-block-list\">\n<li><strong>Iterating Through Workbooks:<\/strong><br>You can loop through all open workbooks using the <code>books<\/code> collection, which internally utilizes the <code>Item<\/code> property:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\napp = xw.apps.active\nfor wb in app.books:\n    print(f\"Workbook: {wb.name}, Sheets: {&#91;sheet.name for sheet in wb.sheets]}\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">This iterates over each workbook and prints its name along with sheet names, demonstrating how <code>Item<\/code> underpins collection access.<\/p>\n\n\n\n<ol start=\"4\" class=\"wp-block-list\">\n<li><strong>Error Handling:<\/strong><br>When accessing by name, if the workbook isn&#8217;t open, xlwings raises a <code>KeyError<\/code>. You can handle this gracefully:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\napp = xw.apps.active\ntry:\n    wb = app.books&#91;'NonExistent.xlsx']\nexcept KeyError:\n    print(\"Workbook not found. Please check if it's open.\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The `Item` member of the `Workbooks` object in Excel&apos;s object model is a property used to access a s&#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-2240","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2240","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=2240"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2240\/revisions"}],"predecessor-version":[{"id":3422,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2240\/revisions\/3422"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2240"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2240"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2240"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}