{"id":2410,"date":"2026-11-04T15:59:07","date_gmt":"2026-11-04T07:59:07","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2410"},"modified":"2026-03-29T10:29:11","modified_gmt":"2026-03-29T10:29:11","slug":"how-to-use-rangelistnames-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangelistnames-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.ListNames in the xlwings API way"},"content":{"rendered":"\n

The ListNames<\/code> property of the Range<\/code> object in Excel’s object model is accessible through the xlwings API, providing a powerful way to retrieve a collection of all defined names that intersect with a specified range. This is particularly useful for auditing, data validation, or dynamically interacting with named ranges within a workbook. In xlwings, this property is exposed as a method on a Range<\/code> object, returning a list of Name<\/code> objects, each representing a defined name in the workbook.<\/p>\n\n\n\n

Functionality:<\/strong>
The primary function is to list all defined names (created via “Formulas” > “Define Name” or through VBA) whose ranges have at least one cell in common with the specified Range<\/code> object. If the specified range does not intersect with any defined names, an empty list is returned. This allows for targeted inspection of named ranges within specific worksheet areas.<\/p>\n\n\n\n

Syntax:<\/strong>
In xlwings, the syntax is:<\/p>\n\n\n\n

range_object.api.ListNames<\/code><\/pre>\n\n\n\n
Here, range_object<\/code> is an xlwings Range<\/code> instance (e.g., sheet.range('A1:D10')<\/code>). The .api<\/code> attribute provides direct access to the underlying Excel object model (via pywin32 on Windows or appscript on macOS). The ListNames<\/code> property does not take any parameters. It returns a pywin32 Names<\/code> collection object, which can be iterated over or converted to a list. Each item in this collection is a pywin32 Name<\/code> object, corresponding to a defined name in Excel.<\/p>\n\n\n\n
Key Points:<\/strong><\/p>\n\n\n\n
    \n
  • The property is read-only.<\/li>\n\n\n\n
  • It returns names defined at both the workbook and worksheet scope, but only if they intersect with the range.<\/li>\n\n\n\n
  • The intersection is based on the actual range referenced by the name, not just its starting cell.<\/li>\n<\/ul>\n\n\n\n
    Example:<\/strong>
    Consider an Excel workbook where the following names are defined:<\/p>\n\n\n\n
      \n
    • SalesData<\/code> referring to Sheet1!$A$1:$F$100<\/code><\/li>\n\n\n\n
    • Quarter1<\/code> referring to Sheet1!$B$1:$B$25<\/code><\/li>\n\n\n\n
    • Summary<\/code> referring to Sheet2!$A$1:$A$10<\/code><\/li>\n<\/ul>\n\n\n\n
      The following xlwings code demonstrates how to use ListNames<\/code>:<\/p>\n\n\n\n
      import xlwings as xw\n\n# Connect to the active workbook\nwb = xw.books.active\nsheet = wb.sheets['Sheet1']\n\n# Define a range on Sheet1\ntarget_range = sheet.range('A1:C30')\n\n# Get the list of names intersecting with this range\nnames_collection = target_range.api.ListNames\n\n# Check if any names were found\nif names_collection:\n    print(\"Names intersecting with range A1:C30:\")\n    for name_obj in names_collection:\n        # Access properties of the Name object\n        name = name_obj.Name # The name string (e.g., \"SalesData\")\n        refers_to = name_obj.RefersTo # The range reference (e.g., \"=Sheet1!$A$1:$F$100\")\n        print(f\" - {name}: {refers_to}\")\nelse:\n    print(\"No defined names intersect with the specified range.\")<\/code><\/pre>\n\n\n\n
      <\/p>\n","protected":false},"excerpt":{"rendered":"
      The `ListNames` property of the `Range` object in Excel's object model is accessible through the xlw…<\/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-2410","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2410","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=2410"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2410\/revisions"}],"predecessor-version":[{"id":3666,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2410\/revisions\/3666"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2410"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2410"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2410"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}