Add-in & Settings


The xlwings add-in is the preferred way to be able to use the Run main button, RunPython or UDFs. Note that you don’t need an add-in if you just want to manipulate Excel by running a Python script.


The ribbon of the add-in is compatible with Excel >= 2007 on Windows and >= 2016 on Mac. On Mac, all UDF related functionality is not available.


The add-in is password protected with the password xlwings. For debugging or to add new extensions, you need to unprotect it. Alternatively, you can also install the add-in via xlwings addin install --unprotected.


0.16.0 新版功能.

The Run main button is the easiest way to run your Python code: It runs a function called main in a Python module that has the same name as your workbook. This allows you to save your workbook as xlsx without enabling macros. The xlwings quickstart command will create a workbook that will automatically work with the Run button.


To install the add-in, use the command line client:

xlwings addin install

Technically, this copies the add-in from Python’s installation directory to Excel’s XLSTART folder. Then, to use RunPython or UDFs in a workbook, you need to set a reference to xlwings in the VBA editor, see screenshot (Windows: Tools > References..., Mac: it’s on the lower left corner of the VBA editor). Note that when you create a workbook via xlwings quickstart, the reference should already be set.


User Settings

When you install the add-in for the first time, it will get auto-configured and therefore, a quickstart project should work out of the box. For fine-tuning, here are the available settings:

  • Interpreter: This is the path to the Python interpreter. This works also with virtual or conda envs on Mac. If you use conda envs on Windows, then leave this empty and use Conda Path and Conda Env below instead. Examples: "C:\Python39\pythonw.exe" or "/usr/local/bin/python3.9". Note that in the settings, this is stored as Interpreter_Win or Interpreter_Mac, respectively, see below!

  • PYTHONPATH: If the source file of your code is not found, add the path to its directory here.

  • Conda Path: 如果是在Windows系统使用conda环境,就在这里输入Anaconda或者Miniconda安装路径,比如: C:\Users\Username\Miniconda3%USERPROFILE%\Anaconda 。注意必须是conda 4.6以上!

  • Conda Env: If you are on Windows and use Anaconda or Miniconda, type here the name of your conda env, e.g. base for the base installation or myenv for a conda env with the name myenv.

  • UDF Modules : 导入UDF的Python模块的名称(不加.py 文件扩展名)。如果有多个模块,用”;”分割。例子: UDF_MODULES = "common_udfs;myproject" 。 缺省情况下导入文件是Excel文件同目录下的同名但是文件扩展名为 .py 的文件。

  • Debug UDFs: 如果要手动运行xlwings COM服务器以便排查错误,就选中本选项,参考 调试.

  • RunPython: Use UDF Server: 使用和UDF相同的COM服务器,因为Python解释器不是每次调用后就关闭,因此能够提高速度。

  • Restart UDF Server: This restarts the UDF Server/Python interpreter.

  • Show Console: Check the box in the ribbon or set the config to TRUE if you want the command prompt to pop up. This currently only works on Windows.


If you use Anaconda or Miniconda on Windows, you will need to set your Conda Path and Conda Env settings, as you will otherwise get errors when using NumPy etc. In return, leave Interpreter empty.

Environment Variables

With environment variables, you can set dynamic paths e.g. to your interpreter or PYTHONPATH:

  • On Windows, you can use all environment variables like so: %USERPROFILE%\Anaconda.

  • On macOS, the following special variables are supported: $HOME, $APPLICATIONS, $DOCUMENTS, $DESKTOP.

User Config: Ribbon/Config File


  • Windows: .xlwings\xlwings.conf in your home folder, that is usually C:\Users\<username>

  • macOS: ~/Library/Containers/

The format is as follows (currently the keys are required to be all caps) - note the OS specific Interpreter settings!



The ONEDRIVE_WIN/_MAC setting has to be edited directly in the file, there is currently no possibility to edit it via the ribbon. Usually, it is only required if you are either on macOS or if your environment variables on Windows are not correctly set or if you have a private and corporate location and don’t want to go with the default one. ONEDRIVE_WIN/_MAC has to point to the root folder of your local OneDrive folder.


当工作簿目录下存在 xlwings.conf 时,功能区或配置文件中的全局设置会被覆盖。


Workbook directory config files are not supported if your workbook is stored on SharePoint.


单独为工作簿配置的属性会覆盖全局配置和工作薄目录级配置: 工作簿级的配置是放在 xlwings.conf 表中的键值对。 用 xlwings quickstart 创建一个新的项目的时候,它会为你创建这样一张表,可以通过把表的名字更改为 xlwings.conf 来激活它。



Sometimes, it might be useful to run xlwings code without having to install an add-in first. To do so, you need to use the standalone option when creating a new project: xlwings quickstart myproject --standalone.

This will add the content of the add-in as a single VBA module so you don’t need to set a reference to the add-in anymore. It will also include Dictionary.cls as this is required on macOS. It will still read in the settings from your xlwings.conf if you don’t override them by using a sheet with the name xlwings.conf.