{"id":1984,"date":"2026-04-05T16:57:16","date_gmt":"2026-04-05T08:57:16","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=1984"},"modified":"2026-03-28T03:55:32","modified_gmt":"2026-03-28T03:55:32","slug":"how-to-use-applicationdeletecustomlist-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-applicationdeletecustomlist-in-the-xlwings-api-way\/","title":{"rendered":"How to use Application.DeleteCustomList in the xlwings API way"},"content":{"rendered":"\n

The DeleteCustomList<\/code> member of the Application<\/code> object in Excel VBA is used to remove a previously defined custom autofill or sort list. In xlwings, which provides a Pythonic interface to Excel’s object model, this functionality can be accessed through the api<\/code> property of an App<\/code> or Book<\/code> object, which exposes the underlying VBA object model. This is particularly useful for managing custom lists programmatically, such as cleaning up temporary lists or resetting configurations in automated Excel tasks.<\/p>\n\n\n\n

Functionality<\/strong>
The primary purpose of DeleteCustomList<\/code> is to delete a custom list that has been added to Excel. Custom lists are often used for custom sorting orders or to define autofill sequences (e.g., a list of department names or project stages). Deleting a list can help maintain a clean Excel environment, especially when lists are created dynamically during a script’s execution and are no longer needed afterward.<\/p>\n\n\n\n

Syntax in xlwings<\/strong>
In xlwings, you call this method via the Application<\/code> object obtained from an xlwings App<\/code> instance. The syntax is:<\/p>\n\n\n\n

app.api.DeleteCustomList(ListNum)<\/code><\/pre>\n\n\n\n
    \n
  • app<\/code>: This is an xlwings App<\/code> object, representing the Excel application.<\/li>\n\n\n\n
  • api<\/code>: This property provides direct access to the VBA Application<\/code> object.<\/li>\n\n\n\n
  • DeleteCustomList<\/code>: The method being called.<\/li>\n\n\n\n
  • ListNum<\/code>: A required parameter of type Integer<\/code>. It specifies the index number of the custom list to delete. The index corresponds to the position of the list in Excel’s custom lists collection, where custom lists are numbered sequentially starting from 1. Note that Excel’s built-in lists (like days and months) cannot be deleted and are not included in this count; the indexing applies only to user-defined custom lists.<\/li>\n<\/ul>\n\n\n\n
    To determine the correct ListNum<\/code> for a specific list, you may need to retrieve it from Excel’s list collection. This can be done by using the GetCustomListNum<\/code> method or by iterating through custom lists if you know the list’s contents. However, DeleteCustomList<\/code> itself does not identify lists by name; it requires the numerical index.<\/p>\n\n\n\n
    Code Example<\/strong>
    Below is an example demonstrating how to use DeleteCustomList<\/code> in xlwings. This script adds a custom list, confirms its addition, and then deletes it. Note that error handling is important because attempting to delete a non-existent list or an out-of-range index will raise a com error.<\/p>\n\n\n\n
    import xlwings as xw\n\n# Start or connect to Excel application\napp = xw.App(visible=False) # Set visible=True to see Excel interface\n\ntry:\n    # First, add a custom list for demonstration\n    custom_list = [\"North\", \"South\", \"East\", \"West\"]\n    app.api.AddCustomList(ListArray=custom_list)\n    print(\"Custom list added successfully.\")\n\n    # Assume we want to delete the most recently added list.\n    # In a real scenario, you might need to find the index dynamically.\n    # Here, we use index 1, assuming it's the first user-defined list.\n    # Note: This might fail if other custom lists exist.\n    list_num = 1 # Index for the custom list to delete\n    app.api.DeleteCustomList(ListNum=list_num)\n    print(f\"Custom list at index {list_num} deleted.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\nfinally:\n    # Close Excel\n    app.quit()<\/code><\/pre>\n\n\n\n
    In this example, list_num<\/code> is hard-coded as 1 for simplicity. In practice, to reliably delete a specific list, you might first use GetCustomListNum<\/code> to find its index based on the list array, or maintain a record of list indices when creating them. The AddCustomList<\/code> method returns the index of the newly created list, which can be stored for later deletion. For instance:<\/p>\n\n\n\n
    # When adding a list, store the returned index\nnew_list_index = app.api.AddCustomList(ListArray=custom_list)\n# Later, delete using the stored index\napp.api.DeleteCustomList(ListNum=new_list_index)<\/code><\/pre>\n\n\n\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    The `DeleteCustomList` member of the `Application` object in Excel VBA is used to remove a previousl…<\/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-1984","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1984","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=1984"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1984\/revisions"}],"predecessor-version":[{"id":3023,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1984\/revisions\/3023"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=1984"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=1984"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=1984"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}