{"id":2331,"date":"2026-09-26T07:23:05","date_gmt":"2026-09-25T23:23:05","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2331"},"modified":"2026-03-28T13:15:09","modified_gmt":"2026-03-28T13:15:09","slug":"how-to-use-worksheetnames-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetnames-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.Names in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">In Excel object model, the <code>Names<\/code> collection refers to all defined names within a workbook, including workbook-level and worksheet-level names. However, in xlwings, the <code>Worksheet<\/code> object does not have a direct <code>Names<\/code> property. Instead, you can access defined names via the <code>Book<\/code> (or <code>Workbook<\/code>) object. Specifically, you can use <code>Book.names<\/code> to retrieve all defined names in the workbook. To get or manage names that are scoped to a particular worksheet, you can filter the <code>Book.names<\/code> collection based on the name&#8217;s scope.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The primary functionality of the <code>Names<\/code> collection in xlwings is to create, read, update, or delete defined names, which are useful for referencing specific ranges, constants, or formulas in a workbook. This can simplify formulas, improve readability, and make your code more maintainable.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax and Usage:<\/strong><br>In xlwings, you interact with defined names through the <code>Book.names<\/code> property. Here\u2019s the basic syntax:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>book.names<\/code>: Returns a collection of all defined names in the workbook. Each item in the collection is a <code>Name<\/code> object.<\/li>\n\n\n\n<li>To access a specific name, you can use indexing or the <code>get<\/code> method: <code>book.names['MyName']<\/code> or <code>book.names.get('MyName')<\/code>.<\/li>\n\n\n\n<li>To create a new name, use <code>book.names.add(name, refers_to)<\/code>, where <code>name<\/code> is the string identifier for the name, and <code>refers_to<\/code> is the formula or range it references (e.g., &#8220;=Sheet1!$A$1:$B$10&#8221;). You can specify the scope by including the worksheet name in the <code>refers_to<\/code> parameter or by setting properties after creation.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">For worksheet-level names, you can filter by checking the <code>name.scope<\/code> property. For example, to get all names scoped to a specific worksheet, you can iterate through <code>book.names<\/code> and compare the scope. However, note that xlwings does not provide a direct <code>Worksheet.names<\/code> property, so this filtering is done manually.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example Code:<\/strong><br>Here\u2019s a practical example using xlwings to work with defined names, focusing on a worksheet context:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to an existing workbook or create a new one\nwb = xw.Book('example.xlsx') # or xw.Book() for a new workbook\nws = wb.sheets&#91;'Sheet1']\n\n# Add a worksheet-level defined name for a range in Sheet1\n# The refers_to string includes the worksheet name to scope it\nwb.names.add(name='MyRange', refers_to=f\"={ws.name}!$A$1:$D$10\")\n\n# Access the defined name and print its details\nmy_name = wb.names&#91;'MyRange']\nprint(f\"Name: {my_name.name}\")\nprint(f\"Refers to: {my_name.refers_to}\")\nprint(f\"Scope: {my_name.scope}\") # This might return the workbook or worksheet, depending on setup\n\n# List all defined names scoped to the specific worksheet (Sheet1)\nworksheet_names = &#91;]\nfor name in wb.names:\n    # Check if the name's scope matches the worksheet; note: scope may be a string or object\n    if hasattr(name.scope, 'name') and name.scope.name == ws.name:\n        worksheet_names.append(name.name)\n    elif isinstance(name.scope, str) and name.scope == ws.name:\n        worksheet_names.append(name.name)\n        print(f\"Names in {ws.name}: {worksheet_names}\")\n\n# Use the defined name in a formula or operation\n# For example, set a value in the named range\nws.range('MyRange').value = &#91;&#91;1, 2, 3, 4] for _ in range(10)] # Fills the range with data\n\n# Delete a defined name if needed\nwb.names&#91;'MyRange'].delete()\n\n# Save and close\nwb.save()\nwb.close()<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>In Excel object model, the `Names` collection refers to all defined names within a workbook, includi&#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-2331","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2331","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=2331"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2331\/revisions"}],"predecessor-version":[{"id":3552,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2331\/revisions\/3552"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2331"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2331"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2331"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}