How can I call a Python Function from Excel?

Calling a Python function from an Excel worksheet

Calling functions from an Excel worksheet is a very common way to expose Python code to Excel users.

Your Python function is registered using the xl_func decorator, and once PyXLL has been loaded (or reloaded) then that function is available to be called from an Excel worksheet in the same way as any other Excel function.

from pyxll import xl_func

@xl_func
def hello(name):
 return "Hello, %s" % name

 =hello("me")

The module that you write your function in has to be added to the list of modules in the pyxll.cfg config file.

See Worksheet Functions (UDFs) for more details.

Calling a Python function as an Excel macro

Excel macros are another way to call user code (including Python code) from Excel. Macros can be attached to controls, like buttons, so that the user can trigger the code. They can also be called from VBA.

Exposing a Python function to Excel as a macro is very similar to exposing it as a worksheet function, except that the decororator xl_macro is used instead of xl_func.

You can read more about macro functions in Python in the section of the docs Macro Functions.

Using a Python function as callback from the Excel ribbon

Adding controls to the Excel ribbon is a great way to present a nice user interface in Excel.

The ribbon is extended by writing some XML and adding it to the pyxll.cfg config file.

Callbacks referenced in the ribbon XML file refer to Python functions, and so if you have a function you want to call in response to a user pressing a button in the ribbon it’s as simple as adding that function (using the full name, eg your_module.function) to the button definition in the XML file.

 <customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
   <ribbon>
     <tabs>
       <tab id="CustomTab" label="Custom Tab">
         <group id="ContentGroup" label="Content">
           <button id="textButton" label="Text Button"
 onAction="ribbon_functions.on_text_button"/>
         </group>
       </tab>
     </tabs>
   </ribbon>
</customUI>

The ribbon definition above links the button “Text Button” to the Python function ribbon_functions.on_text_button.

For more information about customizing the ribbon see Customizing the Ribbon.

Adding right click context menus to call Python functions

Right-clicking on a cell in Excel brings up a context menu. You can add your own items to this context menu and link them to Python functions, so that your function will be called whenever that context menu item is chosen.

This is done by customizing the ribbon XML file (as above), except this time instead of adding an element to the ribbon section, we add it to the contextMenus section.

<?xml version="1.0" encoding="UTF-8"?>
  <customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
   <ribbon>
   <!-- The ribbon and context menus can be specified in the same file -->
   </ribbon>
   <contextMenus>
     <contextMenu idMso="ContextMenuCell">
       <button id="MyButton"
               label="Toggle Case Upper/Lower/Proper"
               insertBeforeMso="Cut"
               onAction="context_menus.toggle_case"
               imageMso="HappyFace"/>
     </contextMenu>
  </contextMenus>
</customUI>

The above XML code adds a right click context menu item that will call the Python function context_menus.toggle_case when selected.

See Context Menu Functions for more details.

Adding menus to the Excel Add-Ins tab with Python

Adding menus to the Excel Add-Ins tab is one of the simplest ways to add Python functions so they can be called from Excel.

Adding the xl_menu decorator to any Python function will automatically add it to a menu in the Excel Add-Ins tab. When the menu item is selected, the Python function is called.

from pyxll import xl_menu, xlcAlert

@xl_menu("Hello!")
def on_hello():
 xlcAlert("Hello!")

See Menu Functions for more information.