Environment Variables
With xlwings Lite, you define environment variables in the add-in itself. Since xlwings Lite runs in the the browser’s sandbox it can’t access anything on your local computer including local environment variables such as USERPROFILE.
Adding an environment variable
Go to xlwings Lite menu (☰) > Environment Variables:
Select the Workbook or Local tab, depending on the scope you want.
Click the
+button.Fill in Name and Value, then click Save.
Restart xlwings Lite via xlwings Lite menu (☰) > Restart.
Important
Environment variables are only loaded while xlwings Lite starts up. Changes have no effect until you restart.
Each tab lists the variables in that scope, where you can reveal a value (eye icon) or delete it (trash icon).
Scopes
The tab you choose determines where the variable is stored:
Scope |
Stored in |
Available in |
|---|---|---|
Workbook |
The active workbook |
That workbook only, on any machine it’s opened on |
Local |
The browser’s local storage |
All workbooks, on this machine only |
If the same name exists in both scopes, Local overrides Workbook. This lets a workbook ship a default value that each user can override on their own machine.
Note
Local environment variables are deleted when the Office cache is cleared, so keep a backup.
Choosing a scope for secrets
Neither scope is encrypted, so the choice depends on who you’re protecting the value from.
Use Local scope for API keys, passwords, and connection strings. The value stays on your machine and is never saved into the workbook, so it isn’t shared when you send the file to someone else. Each user provides their own value.
Use Workbook scope for values that belong to the workbook but aren’t secret, such as a base URL, a region, or a report name.
Warning
Workbook-scoped values travel with the file. Anyone you email the workbook to—or anyone with access to it on SharePoint or in a Git repository—also gets these values. Never store secrets with workbook scope in files you share.
Local-scoped values are readable by any workbook you trust. Trusted workbook code runs under the same browser origin and can read your local environment variables and send them over the network. Only run code from workbooks you trust, and prefer low-privilege, rotatable API keys with spending limits.
See Security for the full picture of how xlwings Lite stores data.
Reading environment variables in your code
Given an environment variable named OPENAI_API_KEY, read it with os.getenv():
import os
import xlwings as xw
from xlwings import script
@script
def sample_script(book: xw.Book):
key = os.getenv("OPENAI_API_KEY")
if key is not None:
print(key)
else:
raise Exception("Store your OPENAI_API_KEY key under Environment Variables!")
This works the same way in custom functions, scripts, and notebooks.
Note
If os.getenv() returns None for a variable you just added, you most likely need to restart xlwings Lite. See Adding an environment variable.
Environment variables and Wingman
Wingman can write code that uses your environment variables. Before anything is sent to your model provider, xlwings Lite replaces their values with placeholders on a best-effort basis; see Wingman for what this covers.