{"id":2387,"date":"2026-10-24T07:08:08","date_gmt":"2026-10-23T23:08:08","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2387"},"modified":"2026-03-29T10:10:29","modified_gmt":"2026-03-29T10:10:29","slug":"how-to-use-rangecreatenames-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangecreatenames-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.CreateNames in the xlwings API way"},"content":{"rendered":"\n

The CreateNames<\/code> method in the Excel object model is a powerful feature for automating the creation of named ranges from a selection. In xlwings, this functionality is exposed through the api<\/code> property, which provides direct access to the underlying Excel object model. This method is particularly useful when you have a range where the top row, left column, bottom row, or right column contains labels that you want to use as names for adjacent cells or ranges. By using CreateNames<\/code>, you can programmatically define these names, enhancing workbook organization and making formulas more readable and maintainable.<\/p>\n\n\n\n

Functionality<\/strong>
The CreateNames<\/code> method generates named ranges based on the labels located at the edges of a specified range. It examines the selected range and uses the labels in the top row, left column, bottom row, or right column to create names for the contiguous cells in the opposite direction. For example, if you have labels in the top row, it will create names for the columns below each label. This is especially beneficial in scenarios like financial models or data tables where you need to assign descriptive names to data blocks dynamically.<\/p>\n\n\n\n

Syntax<\/strong>
In xlwings, you invoke CreateNames<\/code> via the api<\/code> property of a Range object. The method signature is:<\/p>\n\n\n\n

range.api.CreateNames(Top, Left, Bottom, Right)<\/code><\/pre>\n\n\n\n
    \n
  • Top<\/strong> (Optional, Boolean): If True<\/code>, uses labels in the top row to create names. Default is False<\/code>.<\/li>\n\n\n\n
  • Left<\/strong> (Optional, Boolean): If True<\/code>, uses labels in the left column to create names. Default is False<\/code>.<\/li>\n\n\n\n
  • Bottom<\/strong> (Optional, Boolean): If True<\/code>, uses labels in the bottom row to create names. Default is False<\/code>.<\/li>\n\n\n\n
  • Right<\/strong> (Optional, Boolean): If True<\/code>, uses labels in the right column to create names. Default is False<\/code>.<\/li>\n<\/ul>\n\n\n\n
    All parameters are optional, and if none are specified, Excel will guess the label positions based on the range’s layout. Typically, you set one of these to True<\/code> depending on where your labels are located. Note that the method corresponds to the “Create from Selection” feature in Excel’s Formulas tab.<\/p>\n\n\n\n
    Examples<\/strong>
    Here are practical xlwings API code instances demonstrating the use of CreateNames<\/code>:<\/p>\n\n\n\n
      \n
    1. Creating names from top row labels<\/strong>: Suppose you have a range where the first row contains headers like “Revenue”, “Expenses”, and you want to name the data below each header.<\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\n\n# Connect to the active workbook and sheet\nwb = xw.books.active\nsheet = wb.sheets['Sheet1']\n\n# Define the range including headers and data (e.g., A1:C10)\ntarget_range = sheet.range('A1:C10')\n\n# Use CreateNames with Top=True to generate names based on top row\ntarget_range.api.CreateNames(Top=True)\n\n# This will create named ranges like \"Revenue\" for A2:A10, \"Expenses\" for B2:B10, etc.<\/code><\/pre>\n\n\n\n
        \n
      1. Creating names from left column labels<\/strong>: If your labels are in the first column and you want to name the cells to the right.<\/li>\n<\/ol>\n\n\n\n
        import xlwings as xw\n\nwb = xw.books.active\nsheet = wb.sheets['Data']\n\n# Range with labels in column A and data in columns B onward (e.g., A1:D5)\ntarget_range = sheet.range('A1:D5')\n\n# Use CreateNames with Left=True\ntarget_range.api.CreateNames(Left=True)\n\n# This creates names like \"Jan\" for B1:D1 if A2 contains \"Jan\", and so on.<\/code><\/pre>\n\n\n\n
          \n
        1. Combining multiple directions<\/strong>: In complex tables, you might have labels on both top and left. You can call CreateNames<\/code> multiple times or use it with caution, as overlapping names may cause conflicts. Here’s an example for top and left:<\/li>\n<\/ol>\n\n\n\n
          import xlwings as xw\n\nwb = xw.books.active\nsheet = wb.sheets['Sheet1']\n\n# Assume a table with top row headers and left column labels\ntarget_range = sheet.range('A1:E6')\n\n# First, create names from top row\ntarget_range.api.CreateNames(Top=True)\n# Then, create names from left column (if needed, but note potential overwrites)\ntarget_range.api.CreateNames(Left=True)\n\n# It's advisable to manage ranges separately to avoid errors.<\/code><\/pre>\n\n\n\n
            \n
          1. Using without parameters for automatic detection<\/strong>: If the range has a clear layout, you can let Excel decide.<\/li>\n<\/ol>\n\n\n\n
            import xlwings as xw\n\nwb = xw.books.active\nsheet = wb.sheets['Report']\n\n# Select a range where labels are intuitively placed (e.g., A1:B10 with headers in row 1)\ntarget_range = sheet.range('A1:B10')\ntarget_range.api.CreateNames() # Excel guesses label positions\n\n# This is useful for quick automation but may require verification in complex cases.<\/code><\/pre>\n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            The `CreateNames` method in the Excel object model is a powerful feature for automating the creation…<\/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-2387","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2387","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=2387"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2387\/revisions"}],"predecessor-version":[{"id":3634,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2387\/revisions\/3634"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2387"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2387"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2387"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}