{"id":2276,"date":"2026-08-29T15:55:08","date_gmt":"2026-08-29T07:55:08","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2276"},"modified":"2026-03-28T12:15:45","modified_gmt":"2026-03-28T12:15:45","slug":"how-to-use-worksheetcircleinvalid-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetcircleinvalid-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.CircleInvalid in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <code>CircleInvalid<\/code> method in the <code>Worksheet<\/code> object is a useful feature for data validation and error checking in Excel. When applied, it draws red circles around cells that contain data failing any validation rules set for those cells. This visual cue helps users quickly identify and correct invalid entries, enhancing data integrity. In xlwings, this method can be accessed through the <code>api<\/code> property, which provides direct access to the underlying Excel object model, allowing for seamless integration of Excel&#8217;s native functionalities into Python scripts.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The syntax for using <code>CircleInvalid<\/code> in xlwings is straightforward: <code>worksheet.api.CircleInvalid()<\/code>. This method does not take any parameters, as it simply applies the circling effect to all cells in the worksheet that currently violate validation rules. It is important to note that this method is a member of the Excel VBA <code>Worksheet<\/code> object, and xlwings bridges this by exposing it via the <code>api<\/code> attribute. Before calling <code>CircleInvalid<\/code>, ensure that data validation rules are properly set in the Excel worksheet, as the method relies on these rules to determine invalid cells. The circles are drawn based on the active validation criteria, and they can be removed by using the <code>ClearCircles<\/code> method if needed.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">For example, consider a scenario where you have an Excel worksheet with a column for age entries, and you&#8217;ve set a data validation rule to only allow values between 0 and 120. If some cells contain ages outside this range, you can use xlwings to circle those invalid entries. Here&#8217;s a code instance:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active Excel instance or open a workbook\napp = xw.App(visible=True) # Set visible=False for background operation\nwb = app.books.open('example.xlsx') # Replace with your file path\nws = wb.sheets&#91;'Sheet1'] # Specify the worksheet name\n\n# Apply data validation rule (if not already set in Excel)\n# Note: xlwings does not directly set validation; ensure it's pre-configured in Excel.\n# For demonstration, assume validation is already applied in the worksheet.\n\n# Circle invalid cells based on existing validation rules\nws.api.CircleInvalid()\n\n# To remove the circles after correction, you could use:\n# ws.api.ClearCircles()\n\n# Save and close if needed\nwb.save()\nwb.close()\napp.quit()<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The `CircleInvalid` method in the `Worksheet` object is a useful feature for data validation and err&#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-2276","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2276","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=2276"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2276\/revisions"}],"predecessor-version":[{"id":3475,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2276\/revisions\/3475"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2276"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2276"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2276"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}