Settings

Settings control how xlwings Lite behaves. Open them via xlwings Lite menu (☰) > Settings.

Settings are split into two tabs that determine where a setting is stored and how far it reaches:

Tab

Stored in

Applies to

Workbook

The active workbook

That workbook only, on any machine it’s opened on

Local

The browser’s local storage

All workbooks you open in this Excel application

Note

Local settings are deleted when the Office cache is cleared, so keep a backup.

Workbook settings

Because these settings live in the workbook, they travel with the file: if you send the workbook to someone else, they get the same settings.

Startup Behavior

Controls whether xlwings Lite starts automatically when the workbook is opened:

Option

Behavior

Do not autostart

Nothing happens until you click on the xlwings Lite icon in the Home tab (Excel ribbon).

Autostart in the background

Python starts when the workbook opens, without opening the task pane. This is especially helpful if you only work with custom functions.

Autostart and open task pane

Python starts and the task pane opens. This is the default.

If the task pane opens automatically on a workbook where you accidentally opened xlwings Lite, you can stop this behavior by setting the startup behavior to Do not autostart.

App Mode

App Mode hides the code editor and turns each script into a button, which is how you usually hand a workbook to end-users.

  • Show the Output pane: By default, App Mode hides the Output pane. Enable this if your scripts print progress or results that end-users should see.

  • Activate App Mode: Switches the current workbook into App Mode. You can also toggle between Developer Mode and App Mode with Ctrl+Shift+M (Windows) or Cmd+Shift+M (macOS).

Pyodide Version

Pyodide is the WebAssembly-based Python distribution that powers xlwings Lite. Each workbook is pinned to the version it was created with, so an existing workbook keeps working the same way after xlwings Lite ships a newer runtime.

Changing the version affects the Python version and the available package versions, so it can break code that worked before. xlwings Lite will give you the option to resolve to the latest supported package versions automatically though. This, however, also implies that some packages come with major releases, e.g., upgrading from Pyodide 0.27.5 to Pyodide 314.0.1 upgrades pandas from v2 to v3, see also Dependencies.

Important

Make a backup copy of your workbook before changing the Pyodide version.

Local settings

These settings are stored in your browser’s local storage and apply to every workbook you open on this machine. They are never saved into the workbook, so they aren’t shared when you send the file to someone else.

Theme

Sets the color theme of the task pane: Auto (follow Excel), Light, or Dark. The default is Dark.

Wingman

Wingman is the AI assistant for xlwings Lite, see xlwings Wingman. It uses your own API key: requests go directly from your machine to the provider you configure here.

  • Providers: Click + to add OpenAI, Anthropic, Google, OpenRouter or a Custom OpenAI-compatible endpoint (e.g., a self-hosted model), then enter your API key. OpenAI, Anthropic and Google come with a list of models; for OpenRouter and Custom, add at least one model in the same dialog. Changes in the dialog are only stored when you click Save.

  • Custom instructions: Instructions that apply to the Wingman chat in every workbook, see Custom instructions.

  • Wingman custom function: Enables the =WINGMAN() custom function and sets the model it uses.

Important

Wingman calls your provider directly from the browser, so a Custom endpoint must send CORS headers:

Access-Control-Allow-Origin: https://addin.xlwings.org

Use your own domain instead if you self-host the add-in. See Web API Requests for the full CORS picture.

Warning

API keys are stored unencrypted in your browser’s local storage, and any workbook code you run can read them. Use keys with spending limits, and see Wingman security for what Wingman sends to your provider.

Custom Functions

Allow custom functions to return images controls whether custom functions can return images such as Matplotlib figures. Excel can only display an image in a cell by fetching it from a URL, so the rendered image is uploaded to the xlwings image cache while the function calculates, then embedded in the workbook and deleted from the cache. Only the image is uploaded—no raw data or code—but it does require an internet connection during calculation.

Turn it off if you’d rather not have images leave your machine; custom functions returning a figure will then show an error in the cell instead. This doesn’t affect scripts that use mysheet.pictures.add(). See Custom functions that return images.

Note

This setting isn’t shown when you self-host, as the image cache is then part of your own deployment.

Editor

Load sample code for new workbooks controls what new workbooks start with. When enabled (the default), main.py contains sample scripts and custom functions and requirements.txt lists common packages. When disabled, main.py is empty and requirements.txt only contains the required packages.

This affects new workbooks only—workbooks that already have code are never touched.