{"id":2359,"date":"2026-10-10T07:01:37","date_gmt":"2026-10-09T23:01:37","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2359"},"modified":"2026-03-29T09:52:58","modified_gmt":"2026-03-29T09:52:58","slug":"how-to-use-rangeaddcomment-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangeaddcomment-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.AddComment in the xlwings API way"},"content":{"rendered":"\n

The AddComment<\/strong> method in xlwings is a powerful feature that allows developers to programmatically add comment threads (formerly known as “notes”) to specific cells within an Excel worksheet. This functionality is essential for adding annotations, explanations, or instructions directly to cell data, enhancing the clarity and collaborative potential of a spreadsheet. In modern Excel, comments are interactive threads, and xlwings provides a straightforward API to manage them.<\/p>\n\n\n\n

Syntax and Parameters<\/strong><\/p>\n\n\n\n

In xlwings, the AddComment<\/code> method is accessed through a Range<\/code> object. The basic syntax is:<\/p>\n\n\n\n

range_object.add_comment(text)<\/code><\/pre>\n\n\n\n
    \n
  • range_object<\/strong>: This is an xlwings Range<\/code> object, representing the cell or range of cells to which you want to attach the comment. The comment will be anchored to the first cell in this range.<\/li>\n\n\n\n
  • text<\/strong> (str): The required string parameter that contains the text you want to display in the comment thread. This is the body of the comment.<\/li>\n<\/ul>\n\n\n\n
    The method returns an xlwings Comment<\/code> object, which provides properties and methods to further manipulate the comment (e.g., comment.text<\/code> to get or set the text later, comment.delete()<\/code> to remove it).<\/p>\n\n\n\n
    Key Behavior and Notes<\/strong><\/p>\n\n\n\n
      \n
    • If the target cell already has a comment, using add_comment<\/code> will raise a ValueError<\/code>. To safely set or update a comment, you should first check for and delete any existing comment using range_object.comment<\/code> and comment.delete()<\/code>.<\/li>\n\n\n\n
    • The comment is created as a thread. In Excel’s UI, it will appear with the current application user’s name.<\/li>\n\n\n\n
    • xlwings interacts with the Excel Object Model, and add_comment<\/code> maps directly to the Range.AddComment<\/code> method in the VBA object library.<\/li>\n<\/ul>\n\n\n\n
      Code Examples<\/strong><\/p>\n\n\n\n
      Here are practical examples demonstrating the use of add_comment<\/code>:<\/p>\n\n\n\n
        \n
      1. Adding a Simple Comment to a Cell:<\/strong>
        This example adds an explanatory comment to cell B5.<\/li>\n<\/ol>\n\n\n\n
        import xlwings as xw\n# Connect to the active workbook and sheet\nwb = xw.books.active\nsht = wb.sheets.active\n# Add a comment to cell B5\ncomment_obj = sht.range(\"B5\").add_comment(\"Please verify this figure with the Q3 report.\")\nprint(f\"Comment added. Its text is: {comment_obj.text}\")<\/code><\/pre>\n\n\n\n
          \n
        1. Safely Adding or Replacing a Comment:<\/strong>
          This pattern checks for an existing comment and replaces it, preventing errors.<\/li>\n<\/ol>\n\n\n\n
          import xlwings as xw\nwb = xw.books.active\ntarget_cell = wb.sheets[\"Sheet1\"].range(\"C10\")\n# Check for and delete an existing comment\nif target_cell.comment:\n    target_cell.comment.delete()\n    print(\"Old comment deleted.\")\n    # Add the new comment\n    target_cell.add_comment(\"Updated forecast as of 2024-05-17.\")<\/code><\/pre>\n\n\n\n
            \n
          1. Adding Comments Based on Cell Values:<\/strong>
            Automate comment insertion by looping through a data range.<\/li>\n<\/ol>\n\n\n\n
            import xlwings as xw\nwb = xw.books.active\nsht = wb.sheets[\"Data\"]\n# Assume column A has values, add a comment in column B for negative values\nlast_row = sht.range(\"A1\").end(\"down\").row\nfor i in range(1, last_row + 1):\n    value = sht.range(f\"A{i}\").value\n    if isinstance(value, (int, float)) and value < 0:\n        # Clear any existing comment before adding\n        if sht.range(f\"B{i}\").comment:\n            sht.range(f\"B{i}\").comment.delete()\n            sht.range(f\"B{i}\").add_comment(f\"Negative value. Check source transaction.\")<\/code><\/pre>\n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            The **AddComment** method in xlwings is a powerful feature that allows developers to programmaticall…<\/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-2359","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2359","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=2359"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2359\/revisions"}],"predecessor-version":[{"id":3596,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2359\/revisions\/3596"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2359"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2359"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2359"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}