{"id":2006,"date":"2026-04-16T16:14:10","date_gmt":"2026-04-16T08:14:10","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2006"},"modified":"2026-03-28T04:44:15","modified_gmt":"2026-03-28T04:44:15","slug":"how-to-use-applicationontime-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-applicationontime-in-the-xlwings-api-way\/","title":{"rendered":"How to use Application.OnTime in the xlwings API way"},"content":{"rendered":"\n

The OnTime method in Excel’s Application object is a powerful feature for scheduling the execution of a procedure at a specific future time or after a specific time interval. In xlwings, this functionality is accessed through the api<\/code> property, which provides direct access to the underlying Excel object model. This allows for the automation of repetitive tasks, data refreshes, or timed notifications without user intervention, effectively enabling time-driven macros within a Python-controlled Excel environment.<\/p>\n\n\n\n

Functionality:<\/strong>
The primary function is to run a specified VBA macro (procedure) at a predetermined time. It can be used for one-time execution or to set up recurring schedules. While xlwings itself runs Python code, OnTime<\/code> schedules the execution of VBA macros stored in the Excel workbook. Therefore, typical use involves writing a VBA macro that, when triggered, can call back into Python via xlwings’ RunPython<\/code> function or perform native Excel operations. This creates a hybrid automation model.<\/p>\n\n\n\n

Syntax in xlwings:<\/strong>
The call is made through the Excel Application object. The syntax in xlwings is:<\/p>\n\n\n\n

app.api.OnTime(EarliestTime, Procedure, LatestTime, Schedule)<\/code><\/pre>\n\n\n\n
    \n
  • EarliestTime (Required):<\/strong> The time when the procedure should be run. It is a serial Excel date\/time value. In practice, it’s often created using datetime<\/code> or time<\/code> modules. Example: datetime.datetime.now() + datetime.timedelta(seconds=10)<\/code>.<\/li>\n\n\n\n
  • Procedure (Required):<\/strong> A string specifying the name of the VBA macro to run. This macro must be present in a standard VBA module in the workbook (e.g., “Module1.MyMacro”).<\/li>\n\n\n\n
  • LatestTime (Optional):<\/strong> The latest time for the procedure to run. If Excel is not in Ready, Copy, Cut, or Find mode at EarliestTime<\/code>, it will wait until it enters one of these states, but only until LatestTime<\/code>. If omitted, Excel waits indefinitely.<\/li>\n\n\n\n
  • Schedule (Optional):<\/strong> A boolean value. True<\/code> to schedule a new OnTime<\/code> procedure (default). False<\/code> to clear a previously set procedure that has not yet run.<\/li>\n<\/ul>\n\n\n\n
    Code Example:<\/strong>
    This example schedules a VBA macro named “RefreshData” to run 5 seconds from now. The VBA macro itself could contain code to call a Python function or refresh queries.<\/p>\n\n\n\n
    import xlwings as xw\nimport datetime\n\n# Connect to the active Excel instance or create a new one\napp = xw.apps.active\n\n# Calculate the time for execution (5 seconds from now)\nrun_time = datetime.datetime.now() + datetime.timedelta(seconds=5)\n\n# Schedule the OnTime call. The macro \"RefreshData\" must exist in the workbook.\napp.api.OnTime(EarliestTime=run_time, Procedure=\"RefreshData\")\n\nprint(f\"Scheduled 'RefreshData' to run at approximately {run_time}\")<\/code><\/pre>\n\n\n\n
    To cancel a scheduled procedure before it executes, you would call OnTime<\/code> with the same EarliestTime<\/code> and Procedure<\/code>, but set Schedule<\/code> to False<\/code>:<\/p>\n\n\n\n
    # Cancel the previously scheduled \"RefreshData\" macro\napp.api.OnTime(EarliestTime=run_time, Procedure=\"RefreshData\", Schedule=False)<\/code><\/pre>\n\n\n\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    The OnTime method in Excel's Application object is a powerful feature for scheduling the execution o…<\/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-2006","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2006","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=2006"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2006\/revisions"}],"predecessor-version":[{"id":3059,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2006\/revisions\/3059"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2006"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2006"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2006"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}